Introduction
An application program interface (API) is a collection of definitions and protocols that enable software programs to effectively and efficiently communicate with one another.
REST stands for representational state transfer. It is an architectural design that consists of a set of constraints to follow when developing web services.
RESTful API is an API that adheres to the REST architecture. REST APIs typically return data in JSON format and send and retrieve data using the HTTP protocol. The API allows you to create, view, update, and delete resources using the standard HTTP methods.
You can use any library or tool that can make HTTP requests in order to test and interact with the RESTful APIs.
Four components make up each API request:
- The endpoint. This is the URL through which the client communicates with the server.
- The HTTP method. It informs the server of the action the client wants to carry out. The most widely used methods are
PATCHGETPOSTPUTandDELETE. - The headers. Used to transmit extra data, such as authorization, between the server and the client.
- The body. The data that is transmitted to the server.
This tutorial will cover how to use curl to interact with RESTful APIs. curl is a command-line tool for sending or receiving data to or from a remote server. It comes pre-installed on macOS and most Linux distributions.
Curl Options
The curl command has the following syntax:
curl [options] [URL...]
When making requests, we will use the following options:
-X,--request- The HTTP method that will be used.-i,--include- Include the response headers.-d,--data- The data to be sent.-H,--header- Additional header to be sent.
HTTP GET
A specific resource is requested from the server by the GET method.
When making HTTP requests using curl, the GET method is used by default. An example of a GET request to the JSONPlaceholder API to a JSON representation of all posts is shown below:
curl https://jsonplaceholder.typicode.com/posts
Use query params to filter the results:
curl https://jsonplaceholder.typicode.com/posts?userId=1
HTTP POST
A resource is created on the server using the POST method. The resource is overridden if it already exists.
The -d option specifies the data that will be used in the POST request made by the command that follows:
curl -X POST -d "userId=5&title=Hello World&body=Post body." https://jsonplaceholder.typicode.com/posts
The Content-Type header is used to indicate the type of the request body. curl uses Content-Type: application/x-www-form-urlencoded by default when this header is not specified.
Set the body type to application/json to send data in JSON format:
curl -X POST -H "Content-Type: application/json" \
-d '{"userId": 5, "title": "Hello World", "body": "Post body."}' \
https://jsonplaceholder.typicode.com/posts
HTTP PUT
A resource on the server can be updated or replaced using the PUT method. The request data is used to replace all the data from the specified resource.
curl -X PUT -d "userId=5&title=Hello World&body=Post body." https://jsonplaceholder.typicode.com/posts/5
HTTP PATCH
The server resource can be partially updated using the PUT method.
curl -X PUT -d "title=Hello Universe" https://jsonplaceholder.typicode.com/posts/5
HTTP DELETE
The server's specified resource is deleted using the DELETE method.
curl -X DELETE https://jsonplaceholder.typicode.com/posts/5
Authentication
You will need to obtain an access key if the API endpoint requires authentication. Otherwise, the “Access Forbidden” or “Unauthorized” response message will be returned by the API server.
The process of obtaining an access key differs depending on the API you are using. Once you have obtained your access token, include it in the header:
curl -X GET -H "Authorization: Bearer {ACCESS_TOKEN}" "https://api.server.io/posts"
Conclusion
Hope this detailed guide helped you understand how to use curl to make test API requests. Visit the Curl Documentation page, for more information about curl.
If you have any queries, feel free to post a comment below, and we'll be happy to answer them.
