REST API–A to Z

This article contains a summary of notes related to what REST API’s are.

(Care of https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/)

REST API : REpresentational State Transfer Application Programming Interface.

A request to a URL which is the REST API endpoint results in a response containing data which is called the resource.

Anatomy

1. The endpoint (or route)
1. this is the url, which is made up of a root-endpoint, and path and finally the query
2. for example “http://faihofu.blogspot.com/search/label/aws”
   ”www.faihofu.blogspot.com” is the root-endpoint
   ”/search/label/aws” is the path
3. another example “https://www.google.co.uk/search?q=faihofu”
   ”www.google.co.uk” is the root-endpoint
   ”/search” is the path
   ”q=faihofu” is the query
2. The method
3. the headers
4. The data (or body or message)

1 Endpoints

When referring to API documentation, the path me be stated as
“/search/label/:labelvalue”
Any colons within the path denote a variable, which need to be replaced when hitting the endpoint.

2 Method

These are the types of API requests:

1. Get
1. This is the default method to request / read from the endpoint / server
2. Post
1. This creates a new resource / data on the endpoint server
3. Put
1. This updates the resource / data on the endpoint server
4. Patch
1. see PUT
5. Delete
1. This deletes resource / data on the endpoint server

These methods are used to perform one of the actions (CRUD):

• Create
• Read
• Update
• Delete

3 Headers

“Headers are used to provide information to both the client and server.
You can find a list of valid headers on MDN’s HTTP Headers Reference.”

HTTP Headers are property-value pairs that are separated by a colon.
The example below shows a header that tells the server to expect JSON content.
You can send HTTP headers with curl through the -H or --header option.
To view headers you’ve sent, you can use the -v or --verbose option as you send the request, like this:

curl -H "Content-Type: application/json" https://api.github.com -v

4 Data, Body, Message

The data (sometimes called “body” or “message”) contains information you want to be sent to the server.
This option is only used with POST, PUT, PATCH or DELETE requests.
To send data through cURL, you can use the -d or --data option:

curl -X POST <URL> -d property1=value1 -d property2=value2

Authentication

To perform a basic authentication with cURL, you can use the -u option, followed by your username and password, like this:

curl -x POST -u "username:password" https://api.github.com/user/repos

HTTP Status codes and error messages

When a CURL command returns an error (use --verbose to view full details), the error code can be translated using the HTTP status reference:
MDN’s HTTP Status Reference.

CURL (cURL) https://curl.haxx.se/

CURL is a command line tool and library used to transfer data, and in this blog-context, can be used to access / hit API endpoints.

To test if curl is installed, run the following command:

curl –version

Using query parameters

When accessing an endpoint using query parameters, the “?” and “=” need to be escaped in the url.

For example

curl https://api.something.com/somepath\?query\=queryvalue

JSON

API responses are often returned in JSON format.

JSON = JavaScript Object Notation

JSON documents can contain non-structured data, in the form of key-value pairs.

{ "property1": "value1", "property2": "value2", "property3": "value3" }

Example curl commands

curl -u "username:password" https://api.github.com/user/repos -d "{\"name\":\"testrepo12345\"}" curl -u "username:password" https://api.github.com/repos/{username}}/testrepo12345 DELETE curl -u "username:password" https://api.github.com/user/repos