RESTful services

API

API = Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. Each time you use an app like Facebook, or check the weather, you're using an API.

In the context of web development, an API is defined as a set of specifications, such as Hypertext Transfer Protocol (HTTP) request messages, along with a definition of the structure of response messages, usually in an XML or a JavaScript Object Notation (JSON) format.

To read: https://github.com/Asabeneh/30-Days-Of-Python/blob/master/28_Day_API/28_API.md

HTTP

HTTP
  • HTTP — is a communication protocol (application layer) which transports messages over internet between client and server. It is the request-response protocol.

REST

  • Representational State Transfer (REST) is a software architectural style for web services that provides a standard for data communication between different kinds of systems.
    • Arch. style for providing standards between computer systems on web making easier to communicate.
    • Архитектурный стиль с помощью которого описывается структура передачи данных (resources and hypermedia)
  • REST is a standard for exchanging data over the Web between computer systems.
  • REST APIs operate on a request/response system.
  • REST is the way HTTP should be used (its GET, POST, PUT, DELETE methods).
    • CRUD principles are mapped to REST commands to comply with the goals of RESTful architecture
    • Every application which has CRUD (Create, Read, Update, Delete) operation has an API to create data, to get data, to update data or to delete data from a database.
  • Representational = representation of resource, how resources get manipulated.

RESTful API

REST is the set of constraints. RESTful refers to an API adhering (придерживаясь) to those constraints.

RESTful systems, are characterized by how the systems are stateless and separate the concerns of client and server.

While designing the API, sometimes not everybody following rest design styles, so RESTful term was created.

Following all principles of REST for creating API

Web services which conform to the REST architectural style are called RESTful web services which allow requesting systems to access and manipulate the data using a uniform and predefined set of stateless operations.

REST is an arch. style not a standard as HTTP

REST it’s an architectural style that provides constraints that guide API design. Uses HTTP.

In general, REST services are defined and implemented using the following features:

  1. Client Server
  2. Stateless
  3. Cache
  4. Uniform Interface
  5. Layered System
  6. Code On Demand
  • Uniform interface — follow a common: data formats → JSON, logical URI naming, error messages text. HTTP requests usage.
  • Stateless requests — the server does not have to store any context between requests — everything needed is within each request to identify unique client.

    • Nodes should not contain any stateful data as the requests can go to any node. Stateful data includes user information, preferences, sessions, etc. Moving from a stateful system to a stateless system might be a bit difficult.

  • Client-server separation — clients determines how data should be displayed, server parses and sends data.
  • Cacheable — the response can be cached.
  • Resource based (NOUN), identified by URI
    • Performing CRUD operation using HTTP verbs (get, post, put, delete)
      • GET: retrieve data, the equivalent to a read in CRUD APIs
      • POST: add new data
      • PUT: update existing data
      • PATCH: update a subset of existing data
      • DELETE: remove data
    • Representation in JSON, XML
    • IMAGES → multipart request, base64 string, and can be transferred over JSON
    • GET /api/animals: retrieve a list of animals
    • POST /api/animals: add a new animal
    • GET /api/animals/dog: retrieve a single animal by ID
    • PUT /api/animals/dog: update a single animal by ID
    • DELETE /api/animals/dog: delete an animal by ID
  • Sorting, search, pagination and offset
      • image
      image
    1. https://dev.to/jackmarchant/offset-and-cursor-pagination-explained-b89 Offset and Cursor Pagination explained
    2. https://www.pdftron.com/blog/graphql/implementing-graphql-pagination/

Planning REST API

Here is a list of things we need to check while planning to create REST APIs:

  1. Understanding the use case. It is really important to know why you are building the API and what services will the API provide.
  2. Listing down API features to understand what all actions your APIs are going to do. This also includes listing down actions and grouping them together to tackle redundant endpoints.
  3. Identify different platforms that’ll use the API and provide support accordingly.
  4. Plan long term on supporting growth and scaling the infrastructure.
  5. Plan API versioning strategy ensuring continuous support is maintained over different versions of the APIs.
  6. Plan API access strategy, that is, authentication, ACL, and throttling.
  7. Plan API documentation and testing.
  8. Understand how to use hypermedia with your APIs.

Best practices for REST API design

  • REST API Must Accept and Respond with JSON
  • Go with Error Status Codes
  • Don't Use Verbs in URLs
  • Use Plural Nouns to Name a Collection
  • Well compiled documentation
  • Return Error Details in the Response Body
  • Use Resource Nesting users/123/orders/001
  • Versioning the API
  • Allow filtering, sorting, and pagination
  • Cache data to improve performance
  • SSL

Mistakes in designing REST

Mistakes:

  1. Duplicating the CRUD naming in URI GET /GetRecipes or POST /CreateRecipe , no need to write Get or Create in the beginning.
  2. Incorrect usage of PATCH (partial update) and PUT (full update), in PATCH we must include only the part of data that should be updated, but in PUT we must include all fields.
    3. image
  3. Ignoring the ability for simultaneous modification of the same object by different clients. PUT method problems.

    4. For example, first client A fetched the resource, and client B updated the resource. Now client A modified old data, and updated it. And now we’ll lose client B data, because client A send the PUT request, which modifies all.

    SOLUTION: add the “version” field in response body. So, if client A tries to update, 409 HTTP exception will be thrown saying that client A has old version, and client A should get latest data, then update it again. HTTP protocol already includes that If-match ↔ ETag

    FOLLOW-UP: What if we make auto-merge? Depends if, client A wants that data, then it should make sure that it was updated. But if it is some ETL system, no then fast-forward merge?

    image
  4. Don’t ignore the timezone.
    5. "duedatetime": {
	"datetime": "2020-01-25T00:00:00",
	"timezone": "Europe/Berlin"
}
  5. Use correct HTTP SUCCESS Response codes. 204 is No Content, request processed successfully but we don’t get the response body. Used when we delete the object.

SOAP — simple object access protocol.

SOAP is a protocol, while REST is a set of guidelines.

SOAP is preferred when robust security is essential as it provides support for Web Services Security (WS-Security), which is a specification defining how security measures are implemented in web services to protect them from external attacks.

SOAP only exchanges data over XML, and REST provides the ability to exchange data over a variety of data formats. RESTful services are comparatively faster and less resource intensive.

SOAP is highly extensible with other technologies and protocols:

  • Web services addressing (WS-addressing): Packages routing information as metadata within SOAP headers
  • Web services description language (WSDL): Describes what a web service does, and where that service begins and ends
  • XSD = schema definition like JSON schemas

SOAP vs REST (simplicity over standard)

SOAP is a protocol, while REST is a set of guidelines.

  • REST is faster, lightweight, good for web apps, mobile apps, and serverless computing.
  • REST can use JSON, XML, txt, HTML but SOAP uses only XML
  • SOAP is more secure because it standardized how messages are secured and transferred through unique identifiers called tokens.
    • This makes requests heavier
  • Many public APIs follow REST guidelines

Swagger UI

  • Describes the structure of API

API versioning

URI Path http://www.example.com/api/v1/products

Query Params http://www.example.com/api/products?version=1.0

Header Accept: version=1.0

Resources

SuperMade with Super