RESTful API

Altogic, in a nutshell, exposes RESTful APIs for your backend application services. Therefore, it is important to understand key concepts in RESTful APIs to use your app services exposed by Altogic and access 3rd party services and use them effectively in your service designs.
What is a RESTful (REST) API?
Let’s say you are trying to find nearby Italian restaurants on your favorite restaurant review app. You open up your mobile app, type “Italian” into a search field, hit enter, and you see a list of restaurants near your location. A REST API works similarly. You request something, and you get a list of results back from the service you are requesting.
An API is an Application Programming Interface. It is a set of rules that allow applications to talk to each other. The developer creates the API on the server and allows the client to talk to it. In the above example, the server is the application running in the cloud, and the client is the mobile app you use to search for Italian restaurants.
REST determines how the API looks like. It stands for “Representational State Transfer,” and it is a set of rules that developers follow when they create their API. In the above example, the search functionality is an API resource exposed by REST.
In RESTful API, the client and server communicate using the HTTP protocol. The client sends a request to the server, and the server processes this request and sends back a response in return.
The anatomy of a request
It is important to note that a request comprises four key items Method, Endpoint, Headers, and Body. 
Request structure
1. Method
The method is the type of request you send to the server. Following HTTP methods are commonly used in RESTful APIs.
GET − This request is used to get a resource from a server. If you perform a GET request, the server looks for the data you requested and sends it back to you. In other words, a GET request performs a READ operation. This is the default request method.
POST − This request is used to create a new resource or perform an action on a server. If you perform a POST request, the server creates a new entry in the database or performs an action and tells you whether the creation is successful or returns the action results. 
PUT and PATCH − These two requests are used to update a resource on a server. For example, if you perform a PUT or PATCH request, the server updates an entry in the database and tells you whether the update is successful. In other words, a PUT or PATCH request performs an UPDATE operation.
DELETE − This request is used to delete a resource from a server. If you perform a DELETE request, the server deletes an entry in the database and tells you whether the deletion is successful. In other words, a DELETE request performs a DELETE operation.
2. Endpoint
The endpoint is the URL you request for. It has the following structure.
root_endpoint/path/?query_parameters
The root-endpoint is the starting point of the API you’re requesting from. For example, the root-endpoint of SendGrid’s API is https://api.sendgrid.com while the root-endpoint of Twitter’s API is https://api.twitter.com
The path determines the resource you’re requesting for. You can access paths just like you can link to parts of a website. As an example, the endpoint below returns tweets composed by a single user, specified by the requested user id has the root endpointhttps://api.twitter.comand path /users/{id}/tweets
1
https://api.twitter.com/users/{id}/tweets
Copied!
Text between curly brackets {} on a path denotes a variable. You need to replace these variables with actual values when you send your request. In the above example, you need to replace {id} with the actual Twitter id of the user.
The final part of an endpoint is query parameters. Query parameters give you the option to modify your request with key-value pairs. They always begin with a question mark (?). Each parameter pair is then separated with an ampersand (&), like this:
1
?query1=value1&query2=value2&query3=value3
Copied!
For example, when you try to get a list of a user’s tweets on Twitter, you can add several query parameters to your request to modify the results given to you, including whether to include replies or retweets, start and end time of tweets etc.
1
https://api.twitter.com/users/{id}/tweets?exclude=replies&start_time=2021-05-01
Copied!
3. Headers
​Headers are used to provide information to both the client and server. It can be used for many purposes, such as authentication and providing information about the body content. 
HTTP Headers are property-value pairs. The example below shows a header that tells the server to expect JSON content.
1
Content-Type: application/json
Copied!
4. Body
The body (sometimes called “data” or “message”) contains information you want to be sent to the server. This option is only used with POST, PUT, PATCH or DELETE requests. You can send body data in a different format specified in Content-Type header, such as form-data, JSON, text, XML, or binary data.
Altogic uses JSON format in the request body of its exposed RESTful API services.
Below is a request body example in JSON for a RESTful API resource that creates a user in the database.
1
{
2
 "email": "[email protected]",
3
 "firsName": "John",
4
 "lastName": "Adams",
5
 "joinDate": "2021-01-01",
6
 "address": {
7
 "street": "121 West Chestnut",
8
 "city": "Chicago",
9
 "state": "IL",
10
 "zipcode": 60610
11
 }
12
}
Copied!
The anatomy of a response
The RESTful API response comprises three main items response code, response headers, and response body. 
Response structure
1. Response code
Response codes (HTTP status codes) indicate whether a specific REST API request has been completed successfully or not. Responses are grouped in the following classes:
Successful responses (200–299) - Means the request has succeeded.
Redirects (300–399) - Means the request is redirected to another URL.
Client errors (400–499) - Means an error that originates from the client has occurred.
Server errors (500–599) - Means an error that originates from the server has occurred.
2. Headers
Same in structure to a request header (see above). In this case, the header data is returned to the client. The server that is processing the request can add additional response headers that the client can use.
3. Body
Similar in structure to a request body. The response body contains data that is returned to the client. You can also send response body data in a different format specified in the Content-Type header, such as JSON, text, XML, HMTL, or binary data. 
Altogic uses JSON format in the response body of its exposed RESTful API services.
Authentication
Typically using RESTful APIs requires a form of authentication. Authentication proves that you are who you say you are. This is like having a driver's license given by a trusted authority that the requester, such as a police officer, can use as evidence that suggests you are, in fact, who you say you are. In summary, authentication refers to proving the correct identity.
On the same line of thought, developers put measures in place for their RESTful APIs to ensure you perform actions only when you’re authorized to do. Since POST, PUT, PATCH and DELETE requests typically alter the database of an application or GET requests can retrieve sensitive data developers almost always put them behind an authentication wall. 
On the web, there are several ways to authenticate yourself. The most commonly used ones are;
Basic - This is the most straightforward method and the easiest. With this method, the sender places a username: password into the request header. The username and password are encoded with Base64, an encoding technique that converts the username and password into a set of characters to ensure safe transmission.
Bearer - Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token allowing access to a certain resource or URL and most likely is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization request header when making requests to protected resources: Authorization: Bearer <token>
OAuth 2.0 - OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials. This method lets you authenticate yourself with social media networks like Google, Twitter, Facebook, etc.
Altogic uses the Bearer method with API keys as tokens to authenticate requesting parties.