REST API using curl
Hello Everyone
Welcome to CloudAffaire and this is Debjeet.
You can interact with a REST API endpoint from Linux command line using curl command and today we will discuss how to make different REST API requests like HEAD, GET, POST, PUT, PATCH, and DELETE using Linux curl command.
If you wonder what REST API is, you can refer this blog post where I have given all the details to clear your doubts.
REST API using curl
Prerequisite
One Linux system with docker and jq installed
Setup:
We will use a docker container that has REST API application pre-configured for this demo. Login to your Linux shell and execute below command to launch a new docker container.
|
1 2 3 4 5 6 7 8 |
## Install docker https://docs.docker.com/engine/install/ ## Install jq https://cloudaffaire.com/faq/how-to-install-jq/ ## Start sample rest api application docker container run --name myAPI --publish 8080:8080 --detach ericgoebelbecker/resttutorial |
REST API HTTP HEAD request using Linux curl:
The HTTP HEAD method requests the headers that would be returned if the HEAD request’s URL was instead requested with the HTTP GET method. For example, if a URL might produce a large download, a HEAD request could read its Content-Length header to check the filesize without actually downloading the file.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
## HEAD request curl --request HEAD \ --head \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees ## Returns ## HTTP/1.1 200 ## Content-Type: application/json;charset=UTF-8 ## Transfer-Encoding: chunked ## Date: Wed, 05 Jan 2022 03:53:06 GMT |
REST API HTTP GET request using Linux curl:
GET method is used to retrieve resource information or to get information from a REST API endpoint. If the request is success, the endpoint response with a status code of 200 along with the requested data and if failed, response will contain the respective status codes like 404 or 400 etc.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
## GET request (get all employess) curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees | jq '.' ## Returns ## [ ## { ## "employeeId": 1, ## "firstName": "John", ## "lastName": "Doe", ## "email": "john@doe.com", ## "phone": "555-1212" ## }, ## { ## "employeeId": 2, ## "firstName": "Jenny", ## "lastName": "Doe", ## "email": "jenny@doe.com", ## "phone": "867-5309" ## }, ## { ## "employeeId": 3, ## "firstName": "Clark", ## "lastName": "Kent", ## "email": "clark@doe.com", ## "phone": "555-1213" ## } ## ] ## GET request (get specific employes) curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/1 | jq '.' ## Returns ## { ## "employeeId": 1, ## "firstName": "John", ## "lastName": "Doe", ## "email": "john@doe.com", ## "phone": "555-1212" ## } |
Print REST API HTTP GET request details using Linux curl
If you observe the previous two command, we have added –silent option with curl command to get only data from the response using curl command. But if you want to see the entire response details of HTTP GET request, you can include –include and –verbose options with curl command.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
## Get request (header and verbose enabled) curl --request GET \ --include \ --verbose \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/1 ## Returns ## * About to connect() to 127.0.0.1 port 8080 (#0) ## * Trying 127.0.0.1... ## * Connected to 127.0.0.1 (127.0.0.1) port 8080 (#0) ## > GET /api/tutorial/1.0/employees/1 HTTP/1.1 ## > User-Agent: curl/7.29.0 ## > Host: 127.0.0.1:8080 ## > Accept:application/json ## > Content-Type: application/json ## > ## < HTTP/1.1 200 ## HTTP/1.1 200 ## < Content-Type: application/json;charset=UTF-8 ## Content-Type: application/json;charset=UTF-8 ## < Transfer-Encoding: chunked ## Transfer-Encoding: chunked ## < Date: Wed, 05 Jan 2022 04:07:48 GMT ## Date: Wed, 05 Jan 2022 04:07:48 GMT ## ## < ## * Connection #0 to host 127.0.0.1 left intact ## {"employeeId":1,"firstName":"John","lastName":"Doe","email":"john@doe.com","phone":"555-1212"} |
REST API HTTP POST request with data from a file using Linux curl:
POST method is used to create a new resource. If the resource is created successfully the response will contain status code 201 and if failed, response will contain the respective status codes like 404 or 409 etc.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
## Create a new file with employee details cat <<'EOF'> employee.json { "employeeId": 4, "firstName": "Debjeet", "lastName": "Bhowmik", "email": "debjeettoni@gmail.com", "phone": "9876543210" } EOF ## POST request (data from file) curl --request POST \ --silent \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "@employee.json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees | jq . ## Get the new employee details curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/4 | jq '.' ## Returns ## { ## "employeeId": 4, ## "firstName": "Debjeet", ## "lastName": "Bhowmik", ## "email": "debjeettoni@gmail.com", ## "phone": "9876543210" ## } |
REST API HTTP POST request with data from command line using Linux curl:
If you observe the last command, we have passed the employee data from a file in the GET request using –data “<some_path/some_file>”, but you can also directly pass the data with the curl command itself as shown below.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
## POST request (data from command line) curl request POST \ --silent \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data '{ "employeeId": 5, "firstName": "Chandrima", "lastName": "Koley", "email": "chandrima@gmail.com", "phone": "8253288366" }' \ http://127.0.0.1:8080/api/tutorial/1.0/employees curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/5 | jq '.' ## Returns ## { ## "employeeId": 5, ## "firstName": "Chandrima", ## "lastName": "Koley", ## "email": "chandrima@gmail.com", ## "phone": "8253288366" ## } |
How to use environment variable in data option of Linux curl command?
So far, we have learned how to POST with data from file and from command line using Linux curl command. But sometimes you may want to pass the data dynamically using Linux environment variable in your curl command.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
## POST request (data from command line with env variables) export PHONE=9999999999 source ~/.bashrc curl --request POST \ --silent \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data '{ "employeeId": 6, "firstName": "Avik", "lastName": "Dutta", "email": "avik@gmail.com", "phone": "'"$PHONE"'" }' \ http://127.0.0.1:8080/api/tutorial/1.0/employees curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/6 | jq '.' ## Returns ## { ## "employeeId": 6, ## "firstName": "Avik", ## "lastName": "Dutta", ## "email": "avik@gmail.com", ## "phone": "9999999999" ## } |
Next, we will discuss how to update an existing resource using PUT request and different between HTTP PUT and PATCH methods.
REST API HTTP PUT request using Linux curl:
PUT method is used to update or replace an existing resource. If the resource is updated successfully the response will contains status code 200 and if failed, response will contain the respective status codes like 404 or 204 etc.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
## PUT request curl --request PUT \ --silent \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data '{ "employeeId": 6, "firstName": "Senha", "lastName": "Kurin", "email": "skurin@gmail.com", "phone": "1111111111" }' \ http://127.0.0.1:8080/api/tutorial/1.0/employees/6 curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/6 | jq '.' ## Returns ## { ## "employeeId": 6, ## "firstName": "Senha", ## "lastName": "Kurin", ## "email": "skurin@gmail.com", ## "phone": "1111111111" ## } |
REST API HTTP PATCH request using Linux curl:
PATCH is similar to PUT request but can update a subset of the resource without replacing the entire content. For example, if you want to update a specific field in your data then use PATCH request and if you want to update the entire content then use PUT request. If the resource is updated successfully the response will contains status code 200 and if failed, response will contain the respective status codes like 404 or 204 etc.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
## PATCH request curl --request PATCH \ --silent \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data '{ "phone": "0123456789" }' \ http://127.0.0.1:8080/api/tutorial/1.0/employees/6 curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/6 | jq '.' ## Returns ## { ## "employeeId": 6, ## "firstName": "Senha", ## "lastName": "Kurin", ## "email": "skurin@gmail.com", ## "phone": "0123456789" ## } |
REST API HTTP DELETE request using Linux curl:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 |
## DELETE request curl --request DELETE \ --silent \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees/6 curl --request GET \ --silent \ --header "Accept:application/json" \ --header "Content-Type: application/json" \ http://127.0.0.1:8080/api/tutorial/1.0/employees | jq '.' ## Returns ## [ ## { ## "employeeId": 1, ## "firstName": "John", ## "lastName": "Doe", ## "email": "john@doe.com", ## "phone": "555-1212" ## }, ## { ## "employeeId": 2, ## "firstName": "Jenny", ## "lastName": "Doe", ## "email": "jenny@doe.com", ## "phone": "867-5309" ## }, ## { ## "employeeId": 3, ## "firstName": "Clark", ## "lastName": "Kent", ## "email": "clark@doe.com", ## "phone": "555-1213" ## }, ## { ## "employeeId": 4, ## "firstName": "Debjeet", ## "lastName": "Bhowmik", ## "email": "debjeettoni@gmail.com", ## "phone": "9876543210" ## }, ## { ## "employeeId": 5, ## "firstName": "Chandrima", ## "lastName": "Koley", ## "email": "chandrima@gmail.com", ## "phone": "8253288366" ## } ## ] |
How to authorize REST API requests in Linux curl command?
If your REST API endpoint has some authorization mechanism enabled (most have) then you need to authenticate your HTTP request with different authorization schema.
Basic Auth:
It is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic, followed by a space and a base64-encoded(non-encrypted) string username: password. For example, to authorize as username / Pa$$w0rd the client would send.
Bearer Token:
Commonly known as token authentication. It is an HTTP authentication scheme that involves security tokens called bearer tokens. As the name depicts “Bearer Authentication” gives access to the bearer of this token.
API Key:
An API key is a token that a client provides when making API calls. With API key auth, you send a key-value pair to the API either in the request headers or query parameters. Some APIs use API keys for authorization.
Digest Auth:
Digest Authentication communicates credentials in an encrypted form by applying a hash algorithm to the username and the password, the password is converted to response and then it is sent to the server. After that server supplies nonce value, the HTTP method, and the requested URI.
OAuth:
OAuth permits client applications to access data provided by a third-party API. For example, as a user of a service you can grant another application access to your data with that service without exposing your login details.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
## curl with authorization curl --request --header "Authorization: ## Basic Auth (username and password) CRED="$( echo $NAME:$PASSWORD | base64 )" curl --request --header "Authorization: Basic $CRED" \ ## Bearer Token (token/oauth) curl --request --header "Authorization: Bearer ## API Key (keys) curl --request --header "X-API-Key: |
Clean up:
|
1 2 3 4 |
## Remove the docker container and image docker container stop myAPI docker container rm myAPI docker image rm docker.io/ericgoebelbecker/resttutorial |