Web API explained

API stands for Application Programming Interface.

• Application - A computer application e.g. website, mobile apps or desktop computer program.

• Programming - Instructions to complete a task e.g. view a resource, make a digital payment etc.

• Interface – point of interaction between two computer systems. E.g. an endpoint, which is one end of a communication channel.

An API enables two computer systems to communicate with each other by providing the language and contract on how the two systems will interact. A standard API will have specifications and instructions which determines how information can be transferred between two communicating computer systems.

An endpoint is the touchpoint of communication when an API interacts with another system. This includes the place that APIs send requests and where the requested resource lives. API performance relies on its ability to communicate effectively with API Endpoints.

Web Services

There are several design models for web services, but the two most popular are SOAP and REST. While the SOAP webservices relies solely on XML to provide messaging services, the REST webservices offers a more lightweight method, using URLs in most cases to receive or send information.

SOAP – Simple Object Access Protocol.

• Steep learning curve compared to REST.

• Language, platform, and transport independent (REST requires use of HTTP)  

• Standardized with built-in error handling.

• Works well in distributed enterprise environments (REST assumes direct point-to-point communication).

• Automation can be achieved when used with certain vendor or language products.

REST - Representational State Transfer 

• Representation - Typically JSON or XML 

• State Transfer - Typically via HTTP 

• Easy to learn for most developers.

• No expensive tools or frameworks required to interact with REST APIs.

• Uses easy to understand standards such as OpenAPI Specification 3.x

• Fast & Efficient – uses lightweight message formats like JSON and no extensive processing is required while SOAP uses XML for all messages which requires additional parsing and processing.

• Closer to other Web technologies in design philosophy and consequently, can easily evolve with other technologies.

Despite some of the benefits of using a SOAP web service, the flexibility, simplicity and ease of use of REST web service has made it a more popular API of choice in recent time.

REST is simple as a concept because it follows a basic language of HTTP 1.1 hypertext transfer that the entire Web understands. Everything is REST API architecture is all about resources. 

Resources can be operated or interacted with using REST methods.

REST Methods 

Each HTTP method is designed to tell the server what type of action a client wants to take. Actions such as Creating, Reading, Updating or Deleting a resource. 

GET - to retrieve data, but without altering it, from a particular URL

POST - to create or manipulate data and is commonly used on web forms.

PUT - to save an update to the unified resource identifiers (URI)

PATCH - to make a change in a request

DELETE - to remove a specified resource

The REST architecture heavily uses standardised HTTP status codes in client server communication. See more on HTTP Status Codes here. 

Common REST Terminologies –

• Messages - the payload of the action (JSON/XML).

• URI - Uniform Resource Identifier. This is unique string that identifies a resource.

• URL - Uniform Resource Locator. This refers to a URI with network information e.g. https://www.computingfacts.com/.

• Idempotence – refers to the concept of performing an operation multiple times without changing the result. E.g. Refreshing a web page (HTTP GET operation).

• Stateless – this implies that the service or server does not maintain any client state. Each data request and response pair are treated as completely independent from prior/future requests. 

• HATEOAS - Hypermedia As The Engine of Application State