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, or Representational State Transfer, is an architectural software style in which standard HTTP requests are used to provide a simple and consistent approach to requesting and modifying data.

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

  • Simple
  • Fast
  • Lightweight
  • Platform independent
  • Language independent
  • Runs over HTTP
  • Response can be returned in “XML/JSON” format

The 4 Principles of ReST

  • Everything is a resource
  • Each resource is identifiable by a unique identifier (URI)
  • Use the standard HTTP methods
  • Resources can have multiple representation
  • Stateless Communicatio

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.

FileContent Type
JPEGimage/jpeg
mpegvideo/mpeg
htmltext/html
xmltext/xml
textapplication/octet-stream

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)

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • OPTION
  • TRACE
  • CONNECT

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

HTTP VerbActionResponse status code
GETRequest an existing resource
  • 200 OK – If Resource Exists
  • 404 – If Not Found
  • 500 Internal server error for all other errors
PUTCreate or Updte a resource
  • 201 Created – If Resource created
  • 200 – If Updated
  • 500 Internal server error for all other errors
PostUpdate Existing Resource
  • 200 OK – If Resource updated
  • 404 – If Not Found
  • 500 Internal server error for all other errors
DELETEDelete a resource
  • 200 OK – If Resource deleted
  • 404 – If Not Found
  • 500 Internal server error for all other errors

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

  • separation of the representation and the resource
  • Visibility
  • Reliability
  • Scalability
  • Performance

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.

Gary Woodfine

Freelance Full Stack Developer at threenine.co.uk
Helps businesses by improving their technical proficiencies and eliminating waste from the software development pipelines.

A unique background as business owner, marketing, software development and business development ensures that he can offer the optimum business consultancy services across a wide spectrum of business challenges.
π