Restful API
Anurag Srivastava

What is REST
REST is the underlying architectural principle of the web. The amazing thing about the web
is the fact that clients (browsers) and servers can interact in complex ways without the client
knowing anything beforehand about the server and the resources it hosts.
The REST architectural style describes six constraints.
Uniform Interface
Stateless
Cacheable
Client-Server
Layered System

Uniform Interface
The uniform interface constraint defines the interface between clients and servers. It
simplifies and decouples the architecture, which enables each part to evolve independently.
The main guiding principles of the uniform interface are:
Resource-Based
Individual resources are identified in requests using URIs as resource identifiers. The
resources themselves are conceptually separate from the representations that are returned
to the client. For example, the server does not send its database, but rather, some HTML,
XML or JSON that represents some database records expressed.

Uniform Interface
Manipulation of Resources Through Representations
When a client holds a representation of a resource, including any metadata attached, it has
enough information to modify or delete the resource on the server, provided it has
permission to do so.
Hypermedia as the Engine of Application State (HATEOAS)
Clients deliver state via body contents, query-string parameters, request headers and the
requested URI (the resource name). Services deliver state to clients via body content,
response codes, and response headers. This is technically referred-to as hypermedia (or
hyperlinks within hypertext).

Hypermedia as the Engine of Application State
(HATEOAS)
lHATEOAS stands for Hypertext As The Engine Of Application State. It means that hypertext
should be used to find your way through the API.
An example:
GET /account/12345 HTTP/1.1
HTTP/1.1 200 OK
<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<balance currency="usd">100.00</balance>
<link rel="deposit" href="/account/12345/deposit" />
<link rel="withdraw" href="/account/12345/withdraw" />
<link rel="transfer" href="/account/12345/transfer" />
<link rel="close" href="/account/12345/close" />
</account>

Stateless
As REST is an acronym for REpresentational State Transfer, statelessness is key.
Essentially, what this means is that the necessary state to handle the request is contained
within the request itself, whether as part of the URI, query-string parameters, body, or
headers. The URI uniquely identifies the resource and the body contains the state (or state
change) of that resource. Then after the server does it's processing, the appropriate state, or
the piece(s) of state that matter, are communicated back to the client via headers, status
and response body.
So what's the difference between state and a resource? State, or application state, is that
which the server cares about to fulfill a request—data necessary for the current session or
request. A resource, or resource state, is the data that defines the resource representation—
the data stored in the database, for instance. Consider application state to be data that could
vary by client, and per request. Resource state, on the other hand, is constant across every
client who requests it.

Stateless

Cacheable
As on the World Wide Web, clients can cache responses. Responses must
therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent
clients reusing state or inappropriate data in response to further requests. Well-
managed caching partially or completely eliminates some client–server
interactions, further improving scalability and performance.

Cacheable

Client-Server
The uniform interface separates clients from servers. This separation of concerns
means that, for example, clients are not concerned with data storage, which
remains internal to each server, so that the portability of client code is improved.
Servers are not concerned with the user interface or user state, so that servers
can be simpler and more scalable. Servers and clients may also be replaced and
developed independently, as long as the interface is not altered.

Client-Server

Layered System
A client cannot ordinarily tell whether it is connected directly to the end server, or
to an intermediary along the way. Intermediary servers may improve system
scalability by enabling load-balancing and by providing shared caches. Layers
may also enforce security policies.

API
Building an API is one of the most important things you can do to increase the
value of your service. By having an API, your service / core application has the
potential to become a platform from which other services grow.
Facebook, Twitter, Google, GitHub, Amazon
The easier your API is to consume, the more people that will consume it.

API

RESTful API Design Definitions
Resource: A single instance of an object. For example, an animal.
Collection: A collection of homogeneous objects. For example, animals.
HTTP: A protocol for communicating over a network.
Consumer: A client computer application capable of making HTTP requests.
Third Party Developer: A developer who wishes to consume your data.
Server: An HTTP server/application accessible from a Consumer over a network.
Endpoint: An API URL on a Server which represents either a Resource or an
entire Collection.
URL Segment: A slash-separated piece of information in the URL.

Authentication
An app can use one of two forms of authentication - Basic
Auth and Session Auth. All credentials used to access any of
the REST APIs can be used with either style of authentication.

Basic Authentication
Basic Auth - authenticates each individual request using a username and password pair.
The Basic Auth token is reversible, however when all communication is over HTTPS the
security context is completely protected. Basic Auth is trivial to use from HTTP client libraries.
Tools such as cURL provide corresponding command line options.
To use Basic Auth, an app must send an HTTP Authorization header containing the username
and password with every request.
A Basic Auth authorization string is composed of the word Basic followed by a base64-
encoded string containing the username and password separated by a colon.
Simple example:
Auth string (before encoding in base64): Basic myUsername:myPassword
Auth string (after base64 encoding): Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk
Complete authorization header: Authorization: Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk

Session Authentication
Session Auth - authenticates each individual request using a auth token.By using Session
Auth, an app eliminates exposure of passwords on every individual request. Only the initial
request for setting up the session needs to be sent with the username and password.
To use Session Auth, an app must first make a login request to collect an auth token from the
backend. The auth token is returned in the JSON returned in the response. This auth token
can then be used for authentication in subsequent requests across all REST APIs.
The auth token is cryptographically secured and cannot be reversed. Hence, it’s impervious to
forgery. The auth token is cleared from a device when a user is logged out.

Token based authentication
The general concept behind a token-based authentication system is simple.
Allow users to enter their username and password in order to obtain a token
which allows them to fetch a specific resource - without using their username and
password. Once their token has been obtained, the user can offer the token -
which offers access to a specific resource for a time period - to the remote site.

Token based authentication
It will use the following flow of control:
The user provides a username and password in the login form and clicks Log In.
After a request is made, validate the user on the backend by querying in the
database. If the request is valid, create a token by using the user information
fetched from the database, and then return that information in the response
header so that we can store the token browser in local storage.
Provide token information in every request header for accessing restricted
endpoints in the application.
If the token fetched from the request header information is valid, let the user
access the specified end point, and respond with JSON or XML.

Token based authentication

JWTJSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact
and self-contained way for securely transmitting information between parties as a
JSON object. This information can be verified and trusted because it is digitally
signed. JWTs can be signed using a secret (with the HMAC algorithm) or a
public/private key pair using RSA.
Let's explain some concepts of this definition further.
Compact: Because of its smaller size, JWTs can be sent through an URL,
POST parameter, or inside an HTTP header. Additionally, the smaller size
means transmission is fast.
Self-contained: The payload contains all the required information about the
user, avoiding the need to query the database more than once.

JWT
JWT stands for JSON Web Token and is a token format used in authorization
headers. This token helps you to design communication between two systems in
a secure way. Let's rephrase JWT as the "bearer token" for the purposes of this
tutorial. A bearer token consists of three parts: header, payload, and signature.
The header is the part of the token that keeps the token type and encryption
method, which is also encrypted with base-64.
The payload includes the information. You can put any kind of data like user
info, product info and so on, all of which is stored with base-64 encryption.
The signature consists of combinations of the header, payload, and secret key.
The secret key must be kept securely on the server-side. You can see the JWT
schema and an example token below;

JWT
A JWT would look like the following:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MTY5MjkxMDksImp0aSI6ImFhN2Y4ZDBhOTVjIiwic2NvcGVzIjpbInJlcG8iLCJwdWJsaWNfcmVwbyJ
dfQ.XCEwpBGvOLma4TCoh36FU7XhUbcskygS81HE1uHLf0E

JWTif ($credentialsAreValid) {
$tokenId = base64_encode(mcrypt_create_iv(32));
$issuedAt = time();
$notBefore = $issuedAt + 10; //Adding 10 seconds
$expire = $notBefore + 60; // Adding 60 seconds
$serverName = $config->get('serverName'); // Retrieve the server name from config file
/*
* Create the token as an array
*/
$data = [
'iat' => $issuedAt, // Issued at: time when the token was generated
'jti' => $tokenId, // Json Token Id: an unique identifier for the token
'iss' => $serverName, // Issuer
'nbf' => $notBefore, // Not before
'exp' => $expire, // Expire
'data' => [ // Data related to the signer user
'userId' => $rs['id'], // userid from the users table
'userName' => $username, // User name
]

JWT
Please notice that you can define the data structure however you want, there are however some
reserved claims, such as the ones used above:
iat – timestamp of token issuing.
jti – A unique string, could be used to validate a token, but goes against not having a centralized
issuer authority.
iss – A string containing the name or identifier of the issuer application. Can be a domain name and
can be used to discard tokens from other applications.
nbf – Timestamp of when the token should start being considered valid. Should be equal to or greater
than iat. In this case, the token will begin to be valid 10 seconds
after being issued.
exp – Timestamp of when the token should cease to be valid. Should be greater than iat and nbf. In
this case, the token will expire 60 seconds after being issued.

JWTTransforming this array into a JWT is super easy:
$secretKey = base64_decode($config->get('jwtKey'));
/*
* Encode the array to a JWT string.
* Second parameter is the key to encode the token.
*
* The output string can be validated at http://jwt.io/
*/
$jwt = JWT::encode(
$data, //Data to be encoded in the JWT
$secretKey, // The signing key
'HS512' // Algorithm used to sign the token, see https://tools.ietf.org/html/draft-ietf-jose-json-web-
algorithms-40#section-3
);
$unencodedArray = ['jwt' => $jwt];
echo json_encode($unencodedArray);

Data Design and Abstraction
Planning how your API will look begins earlier than you’d think; first you need to
decide how your data will be designed and how your core service / application will
work. If you’re doing API First Development this should be easy. If you’re
attaching an API to an existing project, you may need to provide more abstraction.
Occasionally, a Collection can represent a database table, and a Resource can
represent a row within that table. However, this is not the usual case. In fact, your
API should abstract away as much of your data and business logic as possible.
There are also many parts of your service which you SHOULD NOT expose via
API at all. A common example is that many APIs will not allow third parties to
create users.

Verbs
Surely you know about GET and POST requests. These are the two most commonly used
requests when your browser visits different webpages. The term POST is so popular that it
has even invaded common language, where people who know nothing about how the
Internet works do know they can “post” something on a friends Facebook wall.
There are four and a half very important HTTP verbs that you need to know about. I say
“and a half”, because the PATCH verb is very similar to the PUT verb, and two two are often
combined by many an API developer. Here are the verbs, and next to them are their
associated database call.
GET (SELECT): Retrieve a specific Resource from the Server, or a listing of Resources.
POST (CREATE): Create a new Resource on the Server.
PUT (UPDATE): Update a Resource on the Server, providing the entire Resource.
PATCH (UPDATE): Update a Resource on the Server, providing only changed attributes.
DELETE (DELETE): Remove a Resource from the Server.

Verbs
Route::put('user/{id}', 'UserController@update');
Route::get('/', function (Request $request) {
//
});
Route::delete('foo/bar', function()
{
//
});

Versioning
No matter what you are building, no matter how much planning you do
beforehand, your core application is going to change, your data relationships will
change, attributes will invariably be added and removed from your Resources.
This is just how software development works, and is especially true if your project
is alive and used by many people (which is likely the case if you’re building an
API).

Versioning
Planning ahead to ensure your software can evolve along with the rest of the
tech world is even more essential when you’re developing an API.
Once an API is published, it’s frozen. You can’t change that original code, or
you’ll mess everyone up who has plugged into the API. So you create versions,
build the right tests to give you confidence that the versions will work, and live by
RAD (Rapid Application Development) so that you don’t spin too many wheels
before seeing human interactions with your code.

What is the correct way to version my API?
The "URL" way
A commonly used way to version your API is to add a version number in the URL.
For instance:
/api/v1/article/1234
To "move" to another API, one could increase the version number:
/api/v2/article/1234

Endpoints
An Endpoint is a URL within your API which points to a specific Resource or a Collection of Resources.
If you were building a fictional API to represent several different Zoo’s, each containing many Animals
(with an animal belonging to exactly one Zoo), employees (who can work at multiple zoos) and keeping
track of the species of each animal, you might have the following endpoints:
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/animal_types
https://api.example.com/v1/employees
HTTP Request header.
GET /zoos: List all Zoos (ID and Name, not too much detail)
POST /zoos: Create a new Zoo
GET /zoos/ZID: Retrieve an entire Zoo object
PUT /zoos/ZID: Update a Zoo (entire object)
PATCH /zoos/ZID: Update a Zoo (partial object)
DELETE /zoos/ZID: Delete a Zoo
GET /zoos/ZID/animals: Retrieve a listing of Animals (ID and Name).
GET /animals: List all Animals (ID and Name).
POST /animals: Create a new Animal

Endpoints

Filtering

Filtering
When a Consumer makes a request for a listing of objects, it is important that you
give them a list of every single object matching the requested criteria. This list
could be massive. But, it is important that you don’t perform any arbitrary
limitations of the data.
It is important, however, that you do offer the ability for a Consumer to specify
some sort of filtering/limitation of the results. The most important reason for this is
that the network activity is minimal and the Consumer gets their results back as
soon as possible. The second most important reason for this is the Consumer may
be lazy, and if the Server can do filtering and pagination for them, all the better.
The not-so-important reason (from the Consumers perspective), yet a great
benefit for the Server, is that the request will be less resource heavy.

Filtering
Filtering is mostly useful for performing GETs on Collections of resources. Since
these are GET requests, filtering information should be passed via the URL. Here
are some examples of the types of filtering you could conceivably add to your API:
l?limit=10: Reduce the number of results returned to the Consumer (for
Pagination)
l?offset=10: Send sets of information to the Consumer (for Pagination)
l?animal_type_id=1: Filter records which match the following condition (WHERE
animal_type_id = 1)
l?sortby=name&order=asc: Sort the results based on the specified attribute
(ORDER BY name ASC)

Swagger
The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs
which allows both humans and computers to discover and understand the capabilities of
the service without access to source code, documentation, or through network traffic
inspection. When properly defined via Swagger, a consumer can understand and interact
with the remote service with a minimal amount of implementation logic. Similar to what
interfaces have done for lower-level programming, Swagger removes the guesswork in
calling the service.
Technically speaking - Swagger is a formal specification surrounded by a large ecosystem
of tools, which includes everything from front-end user interfaces, low-level code libraries
and commercial API management solutions.
http://petstore.swagger.io/
http://zircote.com/swagger-php/

Swagger-PHP
A complete framework for "describing, producing, consuming, and visualizing
RESTful web services."
Swagger-PHP is a PHP annotations library for generating Swagger compatible JSON
documentation for your API. The resulting JSON documentation may then be utilized for
internal and external user friendly documentation, API portal sandbox with Swagger UI as
well as client code generation with the Swagger Code Generation tooling.
https://github.com/swagger-api/swagger-ui
https://github.com/swagger-api/swagger-codegen
https://github.com/zircote/swagger-php

Swagger

Rest API Client
Advanced REST client
https://chrome.google.com/webstore/detail/advanced-rest-
client/hgmloofddffdnphfgcellkdfbfbjeloo
Postman
https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl
=en

Thank You