Scribd
Upload
612 views15 pages

Rest API Best Practices

The document discusses best practices for REST APIs including: - REST uses HTTP verbs like GET, POST, PUT, DELETE to perform CRUD operations on resources in a stateless manner allowing for horizontal scaling. - JSON is a widely used data format for REST APIs and practices like JSON schema, standard response formats, and OAuth authorization should be followed. - Tools like ELK stack, StatsD, Nagios and Nginx can be used for logging, metrics, monitoring and load balancing of REST APIs.

Uploaded by

deepak.angrula506
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
612 views15 pages

Rest API Best Practices

The document discusses best practices for REST APIs including: - REST uses HTTP verbs like GET, POST, PUT, DELETE to perform CRUD operations on resources in a stateless manner allowing for horizontal scaling. - JSON is a widely used data format for REST APIs and practices like JSON schema, standard response formats, and OAuth authorization should be followed. - Tools like ELK stack, StatsD, Nagios and Nginx can be used for logging, metrics, monitoring and load balancing of REST APIs.

Uploaded by

deepak.angrula506
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 15

REST API - BEST

PRACTICES
REST
• REST is an architectural style for building web APIs.
Primarily used with HTTP protocol.

• Primary idea is a resource (URI) which represents a


document e.g. http://www.google.com/document

• On this document, REST guidelines suggest mapping


actions to HTTP verbs such as GET, POST etc.

• REST architecture is stateless. There is no state


maintained at the application layer. This design allows
horizontal scaling by simply adding more machines.
REST Concepts

• GET - Used for fetching a resource. It is idempotent, i.e.


multiple GET requests are equivalent to one request.

• POST - Used to creating a new resource at an endpoint.

• PUT - Used for updating a resource. Idempotent.

• DELETE - Used for deleting a resource. Idempotent.


SOAP vs REST
• First class support of SOAP is only available in the java
world. REST over HTTP/JSON is the language of the web.

• SOAP exposes application logic (classes, methods) where


as REST exposes a resource oriented view. REST
operations are well mapped to database operations (useful
in the context of IIB)

• XML is harder to read for humans. REST APIs has a smaller


learning curve and hence is typically faster to implement.

• No complex tooling required for REST.


GraphQL
• Technology developed by Facebook

• Think of it as SQL over an API.

• There is only one endpoint (e.g. /graphql)

• Lesser over head of maintaining multiple urls

• No versioning

• GraphQL is strongly typed.

• Easy to generate documentation automatically

• Server side implementation has a higher learning curve


JSON in REST
• Semi-structured data format inspired from javascript objects. It has become
one of the most widely used data exchange formats on the web.

•
JSON Best Practices -
JSON Schema
• Meta description for JSON data. Describes structure as
well as first layer of validation for JSON data received via
APIs.

•
JSON Best Practices - Standard
Response and Error Codes
• Use a standardised JSON response over all APIs. e.g.

{
“success”: false,
"data": {
"id": 1001,
"name": "Wing"
},
}

{
“success”: false,
“error": {
"code": 404,
"message": "ID not found"
}
}
Authorisation - OAuth
• OAuth standardises mechanisms to verify authorisation of
a user to access an web application or a resource

• Authorisation information is passed in the HTTP header.

• For simple machine-to-machine authorisation (e.g. insurer


-> IIB), OAuth mandated an access_token based
mechanism over HTTPS.

• More advanced grant types supported where the


resource owner is an end user, say a policyholder for
example.
Scaling in REST domain
• Since REST is stateless, the application layer is very lean.

•
Logging Infrastructure
• We use the open source ELK stack for logging.

• Each request is logged with response time giving a view of the


average response time

• ELK

• Elasticsearch - NoSQL database for unstructured data

• Logstash - Log collector with support for syslog over TCP/UDP.

• Kibana - Real time user interface for viewing logs and statistics.

• Statsd collector for metrics data


Monitoring
• Monitoring is required at different levels

• Application

• Hardware infrastructure

• API

• Open source tooling

• Nagios for monitoring

• Heartbeat for load balancing and adding/removing servers to the


pool of available servers.
Nginx

You might also like