API: The Complete Guide to Application Programming Interface

The key idea is that an application doesn’t need to know the details about how the other application works; it only needs to know about how to use the API. This is the concept of abstraction, which makes it possible for new programs to build on top of the hard work encoded into other programs.

There are many kinds of APIs and a mountain of technical definitions. This post will discuss only a few modern APIs in plain language with practical examples and some hands-on components.

It’s difficult to conceptualize a REST API without a concrete example. Suppose there is a RESTful book API service hosted at https://api.fakebooksite.com. Users can create, read, update, and delete books using the API.

The cURL command is an application that can create HTTP requests and is commonly used to interact with REST APIs from the command line. Here is an example of a request one might submit to the books REST API server with the cURL application:

curl \
request GET \

https://api.fakebooksite.com/v1/authors?author=chuck&sort=title:desc

The curl command specifies that the request should use the “GET” HTTP method.

https://

• This is the part of the URL that signals what protocol will be used. In this case, we use the secure HTTP protocol
  • api.fakebooksite.com
• This part of the URL is called the domain. This is what humans use to find servers on the internet (as opposed to IP addresses).
  • /v1/authors/
• This part of the URL is the REST API endpoint. It points to resources on the server. It is often prefixed by an API version so that the API can evolve over time without upsetting those who prefer to use older versions. This endpoint points to the “authors” resource.
  • ?author=chuck&sort=title:desc
• This part of the URL is called the query string which starts with a “?” and encodes query parameters, which are key-value pairs defined with an “=” and separated with “&”. In this case, we specify the name of the author and ask for the response to be sorted by title name in descending (reverse) alphabetical order.

The REST API server application would be written in a way to respond to this kind of request and serve a response. In this case, the books API might retrieve information about books written by “chuck” from a database, perform a sort operation, and send a response to the cURL client in a JSON format.

JSON stands for JavaScript Object Notation. Despite its name, it is simply a standard file format that any language can use to send and receive data over the internet. The next example will send JSON data to a REST API endpoint.

TIP: APIs often respond with data encoded in JSON format. The jq command is a handy tool for parsing json responses. It is useful to pipe the results of a curl command into jq to see a pretty output, like this (-X is a shortcut for --request):

curl -X GET https://my-cool-site.com/v1/cool-quotes | jq

It’s great to receive data from a REST API endpoint, but often we also want to send a “payload” of data to a REST API. Here is an example that creates/updates the book “Chuck’s Cool Book”:

curl \
--request PUT \
--header “Content-Type: application/json” \
--user chuck:chuck-password \
--data ‘{ “author”: “chuck”, “title”:”Chuck’s Cool Book”, “text”: “When       I was a boy, I ate 3 dozen eggs each morning…” }’ \    
  https://api.fakebooksite.com/v1/books 

There are a couple of new things here to notice: - --request PUT

• We are using a different HTTP method. “PUT” usually means we want to provide data the server can use to create a resource or replace a resource if it already exists.
  • --header “Content-Type: application/json”
• Headers are key-value pairs that give the server or client additional information about the request. There are many standard headers, like “Content-Type”. In this case, the client is telling the server that it is going to send a JSON data payload.
  • --user chuck:chuck-password
  • cURL’s --user option creates an “Authorization” header that includes username and password so the server can authenticate the client and decide if it is authorized to have its request fulfilled. In this case, it’s probably a good idea to require users to sign in before they are allowed to post books, otherwise anyone could stuff the database full of whatever books they want.
• It’s also important that the protocol for this API is HTTPS rather than just HTTP. HTTPS means the connection between the client and server is encrypted, so no one can eavesdrop on the connection and steal the user’s password.
  • --data ‘{...}’

We use this option to compose our JSON payload to send to the server. In this case, we define author, title, and book text in JSON format to send to the server.

In summary, the above cURL command will send an HTTP PUT request to the server at the /v1/books endpoint with a JSON payload. When the server receives the PUT request, it would authenticate the user, check whether the user is authorized to create that resource, perhaps update a database record for that book, and then return a response to the client (e.g. status code 200 to report success).

NOTE: The server might behave very differently depending on which HTTP method is used. In this case, a GET request to https://api.fakebooksite.com/v1/books?author=chuck&title=Chuck%27s+Cool+Book might not require authentication at all and give a response that includes the contents of “Chuck’s Cool Book” in JSON format.

GraphQL specifies three execution operations:

• Query (retrieve data from the server)
• Mutation (change data on the server)
• Subscription (subscribe to a stream of data events from the server)

Source: https://apihandyman.io/do-you-really-know-why-you-prefer-rest-over-rpc/#examples

Notice RPC APIs only use POST and GET HTTP methods, choosing to let the endpoint describe what kind of operation is taking place. Compare that to REST, where DELETE, GET, POST, and PUT methods to the same resource endpoint will result in different behaviors.