curl

Name

curl - transfer a URL

Purpose

To craft HTTP(s) requests and receive HTTP(s) responses allowing transference of data to or from a server.

Usage

curl [url]

Make and receive web requests.

Example

Make a curl request to google.com receiving an HTML object as a response.

curl www.google.com

Result:

The default HTTP method argument in curl is HTTP GET request. To send other types of requests curl requires the type of HTTP request method to be provided by adding the -X [HTTP METHOD] option.

curl Options:

• -H or --header: Specifies an extra header to include in any HTTP request being sent to a server. You can specify any amount of extra headers.
• -X [HTTP METHOD] or --request [HTTP METHOD]: specify what type of HTTP request you want to send to the server.
• -s or --silent: Silent mode. When added to a curl request you will not see a progress meter or any error messages.
• -d or data <data>: Sends specific data in a POST request to the HTTP server.

Setup

This article utilizes the Java Spring Rest API .

sudo apt update -y
sudo apt install openjdk-11-jre

Clone Project Repository

Clone the project repository to your home directory:

git clone https://github.com/LaunchCodeTechnicalTraining/spring-todo-api-jar

Validation

Look at the home directory contents for the newly created spring-todo-api-jar/ directory:

ls

Output:

Run the Application

We will be using Java Runtime Environment (openjdk-11-jre) to run the included .jar file.

Change to the project directory and run the application with:

java -jar todo-api.jar

Output:

The command executed the .jar file which started the Tomcat development server of the project. It will stay attached to this terminal window until we are done with this article.

student@student-VirtualBox:~/spring-todo-api-jar

Activity

To practice curl we will be sending requests to the spring-todo-api. It is a RESTful API that accepts HTTP GET, POST, PATCH, and DELETE requests.

The spring-todo-api allows the following requests:

• GET /todos: request a JSON list of all existing todo items
• POST /todos & JSON Request Body of a new Todo Item: create a new todo item
• PATCH /todos/{id}: changed the completed status of a todo item to true of the path variable {id}
• DELETE /todos/{id}: delete the todo item of path variable {id}

Make a GET request with JSON attached

Making a GET request to the spring-todo-api will result in a list of all of the recorded todo items. As the project has just started we expect to see an empty JSON list: [].

curl localhost:8080/todos -H Content-Type:application/json

Output:

[] is the expected output for this first request.

Make a POST request with JSON attached

Making a POST request to the spring-todo-api and including a JSON representation of a new todo item should save the item in the todo list.

As this is a POST request the -X POST option will need to be provided.

Also a JSON representation of a new todo item will need to be sent in as the request body as indicated by the -d option followed by a JSON string representation of a new todo item.

curl -X POST localhost:8080/todos -H Content-Type:application/json -d '{"text":"the first task"}'

Output:

The spring-todo-api is configured to return a JSON response of the newly created todo item, in this case:

{"id": 1, "text": "the first todo", "completed": false}

Make a PATCH request with JSON attached

Making a PATCH request requires a path variable of an existing todo item id. The API changes the completed parameter of the specific todo item (as identified by the id) to true.

In this case execute a PATCH request to first todo item created that has the id of 1:

curl -X PATCH localhost:8080/todos/1 -H 'Content-Type:application/json'

Output:

The spring-todo-api responded with the JSON representation of the newly updated todo item:

{"id": 1, "text": "the first todo", "completed": true}

The "completed" property of the todo item was set to true from the original value of false.

Validation:

You have created a new todo through a POST request and made a minor update with a PATCH request. Check your changes with another GET request:

curl localhost:8080/todos

The GET requests returns a list of all todo items that currently exist. In this case one completed item exists.

Make a DELETE request

Making a DELETE request requires a valid todo item id, but is otherwise similar to the PATCH request.

Delete the existing todo item that we recently marked as complete:

curl -X DELETE localhost:8080/todos/1

The spring-todo-api does not return a JSON body as the the item was deleted. However, a new GET request will

Output:

Recap:

• curl: tool to transfer data to or from a server.
• curl options:
  • -H or --headers: Specify headers for request
  • -X or --request: Specify what type of request you want to make
  • -s or --silent: Hide progress and error messages
  • -d or --data: Data included in POST request
• Send HTTP requests to an existing REST API
  • GET: Retrieve data from desired resource
  • POST: Submit data to desired resource
  • PATCH: Replace data of a desired resource
  • DELETE: Delete target resource