what is a RESTful API?

Modern Software applications are required to connect across different devices and User Interfaces (UI) enabling the ability to access and manipulate data.  To enable this software developers often create an Application Programming Interface (API).

What is an API ?

An application-programming interface (API) is a set of programming instructions and standards for accessing a Web-based software application or Web tool. A company may release its API to the public so that other software developers can design products that are powered by its service. Thus gradually increasing the opportunities for adoption across a wider user base.

API's are often implemented in the form of services and there are a number of different software design and architectural patterns  including SOAP, CORBA, RPC & ReST.  The one thing that most of these style have in common is that they all use HTTP to enable calls between machines.

ReST Definition

ReST is an acronym for Representational State Transfer, which in itself probably doesn't provide any further clarity on what it actually means.  At it's core, ReST relies on a stateless, client-server, cacheable communications protocol based on HTTP.

ReST is an architectural pattern for designing networked applications using simple HTTP actions to make the calls.  All four CRUD (Create/Read/Update/Delete) operations are made available.

In a RESTful style of API, data resources are allocated unique URLs and manipulated through standard HTTP verbs such as GET to request a resource, POST to create a resource, PUT to change a resource, and DELETE to remove a resource.

ReST services are fully featured , lightweight and simpler to implement compared to other more complex mechanisms like Remote Procedure Calls (RPC),  or WebServices (SOAP, WSDL etc).

Other than adhering to simple HTTP protocols there are no other standards that ReST services are confined or adhere to.  There are no W3C recommendations for REST making it more of an architectural pattern.

Key Features

The 4 Principles of ReST

Principle 1 - Everything is a resource

The concept behind this principle is that of representing data by a specific format and not by a physical file.  Each piece of data available on the internet has a format that could be described by a content type.

[ebs_table width ="100%" style ="table-striped table-bordered" responsive ="true"] [ebs_table_head] [ebs_th_column]File[/ebs_th_column] [ebs_th_column]Content Type[/ebs_th_column] [/ebs_table_head] [ebs_table_body] [ebs_table_row] [ebs_row_column]JPEG [/ebs_row_column] [ebs_row_column]image/jpeg[/ebs_row_column] [/ebs_table_row] [ebs_table_row] [ebs_row_column]mpeg[/ebs_row_column] [ebs_row_column]video/mpeg[/ebs_row_column] [/ebs_table_row] [ebs_table_row] [ebs_row_column]html[/ebs_row_column] [ebs_row_column]text/html[/ebs_row_column] [/ebs_table_row] [ebs_table_row] [ebs_row_column]xml[/ebs_row_column] [ebs_row_column]text/xml[/ebs_row_column] [/ebs_table_row] [ebs_table_row] [ebs_row_column]text[/ebs_row_column] [ebs_row_column]application/octet-stream[/ebs_row_column] [/ebs_table_row] [/ebs_table_body] [/ebs_table]

Principle 2 - each resource is identifiable by a unique identifier

The internet contain many different resources therefore they should all be accessible via Unique Resource Identifiers (URI).  The URI's can be in a human readable format, despite that their consumers are more likely to be software applications rather than humans.

Software developers will no doubt be developing applications to consume REST API's will be humans and will need to understand the details of the API. The URI keeps the data self descriptive and eases further development. This also helps to reduce logic errors.

Principle 3 - Use standard HTTP methods

The native HTTP protocol defines eight actions (A.k.a Verbs)

In the context of defining resources the the first four are a natural fit for defining actions for resource manipulation.  Transposing the concepts to the general purpose of most applications is to perform CRUD (Create, Read , Update and Delete) , which correlate to basic database functionality of INSERT, SELECT, UPDATE & DELETE.

If you apply the REST Principles correctly the HTTP Verbs should be used as shown[ebs_table width ="100%" style ="table-striped table-bordered" responsive ="true"] [ebs_table_head] [ebs_th_column]HTTP Verb[/ebs_th_column] [ebs_th_column]Action[/ebs_th_column] [ebs_th_column]Response status code[/ebs_th_column] [/ebs_table_head] [ebs_table_body] [ebs_table_row] [ebs_row_column]GET[/ebs_row_column] [ebs_row_column]Request an existing resource[/ebs_row_column] [ebs_row_column][ebs_list] [ebs_li type="glyphicon-ok"]200 OK - If Resource Exists[/ebs_li][ebs_li type="glyphicon-ok"]404 - If Not Found[/ebs_li][ebs_li type="glyphicon-ok"]500 Internal server error for all other errors[/ebs_li][/ebs_list][/ebs_row_column] [/ebs_table_row] [ebs_table_row] [ebs_row_column]PUT[/ebs_row_column] [ebs_row_column]Create or Updte a resource[/ebs_row_column] [ebs_row_column][ebs_list][ebs_li type="glyphicon-ok"]201 Created - If Resource created[/ebs_li][ebs_li type="glyphicon-ok"]200 - If Updated[/ebs_li][ebs_li type="glyphicon-ok"]500 Internal server error for all other errors[/ebs_li][/ebs_list][/ebs_row_column] [/ebs_table_row] [ebs_table_row] [ebs_row_column]Post[/ebs_row_column] [ebs_row_column]Update Existing Resource[/ebs_row_column] [ebs_row_column][ebs_list][ebs_li type="glyphicon-ok"]200 OK - If Resource updated[/ebs_li][ebs_li type="glyphicon-ok"]404 - If Not Found[/ebs_li][ebs_li type="glyphicon-ok"]500 Internal server error for all other errors[/ebs_li][/ebs_list][/ebs_row_column] [/ebs_table_row] [ebs_table_row] [ebs_row_column]DELETE[/ebs_row_column] [ebs_row_column]Delete a resource[/ebs_row_column] [ebs_row_column][ebs_list][ebs_li type="glyphicon-ok"]200 OK - If Resource deleted[/ebs_li][ebs_li type="glyphicon-ok"]404 - If Not Found[/ebs_li][ebs_li type="glyphicon-ok"]500 Internal server error for all other errors[/ebs_li][/ebs_list][/ebs_row_column] [/ebs_table_row] [/ebs_table_body] [/ebs_table]

Principle 4 - Resources can have multiple representations

A key feature of a resource is that they may be represented in a different form than the one it is stored. It can be requested or posted in different representations, as long as the specified format is supported.  After the request execution, the resource is left in a final state, which implicitly means that partial resource updates are not supported. You should always send the complete state of the resource.

Principle 5 - Stateless Communication

Resource manipulation operations through HTTP requests should always be considered atomic. All modifications of a resource should be carried out within an HTTP request in isolation. After the request execution, the resource is left in a final state, which implicitly means that partial resource updates are not supported. You should always send the complete state of the resource.

Goals of REST

Security

ReST does not have any built in security features like encryption, session management,  Quality of Service (QoS) guarantees etc. and these are the responsibility of the software developer to implement.

JSON data Format

JSON, or JavaScript Object Notation, is an open, standard format for storing and exchanging data. It is easier to use than XML, is more compact, and can be used as a data format by any programming language. This makes it ideal for HTTP-based API services.

A great resource for learning more about JSON can be found at json.org

What is a REST API Call

The real purpose of API is to provide a set of procedures, protocols & tools to assist in the development of software applications. APIs are a common industry approach to enable various software applications to easily integrate and provide functionality. Enhancing user functionality across a wider business ecosystem

A good API makes it easier to develop a program by providing all the building blocks enabling software developers to assemble these blocks together. An API may be for a web-based system, operating system, database system, computer hardware, or software library and will detail below the types of APIs.

Every time you make a call to a server in name of an application using a SDKs or a API, it counts as an API request or API call. Logins, saves, queries are examples of operations counted as API requests among other types of operations.

Consider a smartphone app, Once installed and you open it, the application may ask your Email and Password to register. Once you submit your data, this will be sent to an API, this is referred to a an API request.