Modern Software applications are required to connect across different machines , User Interfaces (UI) and provide data to other applications in the form of services.  To enable this software developers often create an Application Programming Interface (API).  In this post I’ll provide an explanation of what is rest and how it can be used within your application. This article will discuss fundamentals of Web ReST API are the same regardless of software implementation platform.

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 software company releases its API to the public so that other software developers can design products that are powered by its service.

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.

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
  • Fas
  • 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.

File Content Type
JPEG image/jpeg
mpeg video/mpeg
html text/html
xml text/xml
text application/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.  The point being that software developers who 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 Verb Action Response status code
GET Request an existing resource
  • 200 OK – If Resource Exists
  • 404 – If Not Found
  • 500 Internal server error for all other errors
PUT Create or Updte a resource
  • 201 Created – If Resource created
  • 200 – If Updated
  • 500 Internal server error for all other errors
Post Update Existing Resource
  • 200 OK – If Resource updated
  • 404 – If Not Found
  • 500 Internal server error for all other errors
DELETE Delete 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.




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.
π