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
