0xCODE
Published in

0xCODE

The RESTful Architectural Framework Of Full Stack Development

The REST Framework Methodology For Application Developers

Representational State Transfer (REST) is a web application development architectural framework. Data is represented as resources which are accessed using a standard set of methods, using a common protocol among nodes on the network. Applications that use REST are able to use a standard way of processing data that uses web resources. The client’s running the applications use an API (Application Programming Interface) to communicate with server’s that provide the information using the web. This is a part of the full stack development methodology in software engineering.

In the REST architectural framework, the server does not store state information about the client’s session. This is referred to as the property of statelessness or stateless restriction. This means that the state to handle the request is contained within the request itself. This puts the storing and handling of the session state directly under the client application’s responsibility.

A stateless feature has advantages for developers. It makes the REST APIs less complex by removing the synchronization on the server side. If the server had to keep track of all states, it would not be able to scale to handle millions of transactions at once. Instead it treats each session quickly, without having to establish state information related to session dependency. The state information (e.g. context, request identification, previous interactions) is sent with the request from the client rather than the server storing the information for the client.

METHODS

The basic principle of this framework, also called RESTful application development, is the use of HTTP methods. REST refers to resources which can be accessed using a standard method of requests and responses. You send a request and you receive a response. These are API calls that invoke a method to carry out a routine on the server and send the results back to the client.

The following are the most common HTTP methods used.

GETPUTDELETEPOST

The REST API use endpoints to communicate between a client and server. The client uses HTTP methods to make certain calls to retrieve and store information on the server. The most common way data is exchanged is using a representational resource that all or most systems support. These use data formats like JSON, XMP or serialized PHP among others.

When the GET or POST method is used correctly with a request, it should return an HTTP 200 OK status code. For PUT or DELETE it is either a 204 (no content) or 201 (created). (Review HTTP Status Codes)

ACCESS TOKENS AND API KEY

Unless an API is public and open to all developers, some companies limit access to their servers. This is due to the sensitive information they have stored which can only be provided to those who have permission. You can implement a domain like in Windows to grant permission to users who login, but on the web it is different.

An API Key or access token can be provided to the client for authorization to access a resource, in this case the server. This is provided to client applications, and is not available to the general public. An example of using an API Key is shown in this GET method:

GET /resource?api_key=<value of API Key>

An API Key can be generated from a provider’s website. This usually requires either an e-mail request to the provider or an API Key generation which can be done on the provider’s website. This creates the API Key and allows developers to begin building their software using the API calls. An API Key is a form of authorization that grants the developer’s application access to a system using an endpoint. The following is an example of an API Key:

vaCELgL.0infnf8mVLWwsBbwjYr4Rx-Afh0dDqtly

It looks like a string of characters that is actually a cryptographic hash produced by the provider that grants access to their system. An API Key is not the same as a password, it is separate from it and can even be easily disposable. They are also unique to each application and user to guarantee they are not reused.

The following example is from Infobip, a secure messaging application, on how to generate an API Key.

POST https://{base_url}/settings/1/accounts/{accountKey}/api-keys

This uses the POST method to allow a user to generate the {accountKey} that creates the API Key. Creating an API Key is either allowed to the public or only available upon request, and the reason is due to how sensitive the data on the server’s provider is. Sometimes data cannot be shared publicly unless a user has permission or authorization (e.g. a user’s bank account balance).

In Facebook, an app can request an access token for a user’s profile. When a user grants an app permission, the app can get the access token. Here is an example from the JavaScript SDK.

<!DOCTYPE html>
<html>
<head><title>Get User Access Token</title></head>

<body>

<h1>Get an Access Token using JavaScript SDK</h1>

<p><a href="#" onClick="logInWithFacebook()">Log In with the JavaScript SDK</a></p>


<script>

<!-- Log User in -->

logInWithFacebook = function() {
FB.login(function(response) {
if (response.authResponse) {
alert('You are logged in & cookie set!');
// Redirect the user to token.php file to use the token
window.location.href = "https://your-url.com/token.php";
} else {
alert('User canceled login or did not fully authorize.');
}
});
return false;
};

<!-- Initialize JS SDK to use JS helper to get access token -->

window.fbAsyncInit = function() {
FB.init({
appId: '{your-app-id}',
cookie: true, // This is important, it's not enabled by default
version: 'v5.0'
});
};

(function(d, s, id){
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) {return;}
js = d.createElement(s); js.id = id;
js.src = "https://connect.facebook.net/en_US/sdk.js";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));

<!-- Get user access token -->

FB.getLoginStatus(function(response) {
if (response.status === 'connected') {
var accessToken = response.authResponse.accessToken;
}
} );


</script>

</body>
</html>

A developer must request for an API Key and user access token in order to send requests with responses to a service provider. In order to get information about Twitter or Facebook users on those platforms, the developer must have approval along with the API Key and access token (see developer website for those platforms).

REQUEST

The request uses the following structure:

REST API Endpoint URL + API Method + Parameters

To understand the format of the structure, let us use an example, using Trumail’s e-mail verification API (public).

https://api.trumail.io/v2/lookups/{{format}}?email={{email}}

REST API Endpoint URL:

https://api.trumail.io/v2/lookups/ (This is where the requests are passed)

The URL specifies the HTTPS (Secure HTTPS) protocol at FQDN api.trumail.io at directory v2 and sub-directory lookups on the backend server. The HTTPS protocol secures the connection between the client and server using a trusted CA (Certificate Authority) which issues a digital certificate that verifies the validity of the web provider (in this case Trumail). It is an end-to-end encrypted connection to prevent data leaks and MITM (Man-in-the-Middle) attacks.

API Method:

The API uses a GET method to retrieve information about a user’s e-mail account with the format response specified. This is written in the following structure:

GET /v2/lookups

Parameters:

At the end of the API call string are the parameters. We start with the {{format}}? parameter which specifies the type to return.

The following are example formats that can be returned:

  • JSON
  • XML
  • JSONP

Other formats include:

  • SOAP
  • Serialized PHP
  • HTML

The e-mail address that needs to be verified is passed as the parameter to the method. This is written in the following structure:

email={{email}}

EX: If we want to verify an e-mail address xuser@0xcode.com with a return response format in JSON, we make an API call using the following structure:

https://api.trumail.io/v2/lookups/JSON?email=xuser@0xcode.com

The example from Trumail used an open public API. What if the provider of the information requires an API Key?

To present a request using an API Key, an example can be taken from Emailchecker, the main company that provides a backend to Trumail. Their example when using the API Key uses the following structure:

https://api.emailverifyapi.com/v3/lookups/{{format}}?email={{email}}&key={{API Key}}

The addition of the parameter &key={{API Key}} specifies where to add the API Key when making the request.

RESPONSE

The following is an example of the response to the Trumail e-mail verification API.

{
“address”: “xuser@0xcode.com”,
“username”: “xuser”,
“domain”: “0xcode.com”,
“suggestion”: “”,
“validFormat”: true,
“deliverable”: true,
“fullInbox”: false,
“hostExists”: true,
“catchAll”: false,
“gravatar”: false,
“role”: false,
“disposable”: false,
“free”: false
}

This is in JSON format, which can further be parsed and formatted using a script to organize or extract data. The response is the representational state transfer of the resource, which is the information about the resource.

From the response, we can see that the e-mail address (this is a theoretical example only) exists from the field labeled “hostExists” : true and “deliverable”: true. While this is the response for a valid format, an invalid account will not appear like this at all. There are different types of responses depending on the API construction and supported formats by the provider.

SYNOPSIS

REST is an architectural framework that is used as one of the components of full stack software development. It provides a standard way of requesting data from an application using an API, transmission protocol using HTTPS (security) and format for data interchange. The resulting data is presented in a response format (e.g. JSON, XML, etc.) that the application can understand, allowing the developer to further process it into useful information.

While there are many open public API, others require approval from the provider and the use of an API Key and user access token. These are for more privacy concerned websites that store non-public data like financial, personal and confidential information.

The RESTful application development provides a standard way to create web applications. By defining resources on the web, REST provides a way to allow applications to interact with services using a protocol that any developer can use. It offers developers on how to request information, allowing the use of HTTP strings from web browsers or terminal console to send requests to a server, as alternatives to coding in applications. This helps bring flexibility and interoperability across the Internet through the web.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Vincent Tabora

Vincent Tabora

Editor HD-PRO, DevOps Trusterras (Cybersecurity, Blockchain, Software Development, Engineering, Photography, Technology)