Hosted Web Endpoints Flashcards
What is REST?
REpresentational State Transfer has emerged as the common approach for communication within modern client-server solutions.
It uses protocols that were originally made to server and enable the World Wide Web, in particular REST uses concepts from the HTTP protocol.
Architecture style for designing networked applications
Relies on a stateless, client-server protocol - almost always HTTP
Treats server objects as a resources (data, file, feed etc). Resources can be created or destroyed.
A primary advantage of REST over HTTP is that is uses open standards and doesn’t not bind the implementation of the API or client applications to any specific implementation. This means it can be used with almost any programming language.
What are some of the main design principles of RESTful APIs?
They are designed around resources, which are any kind of object, data or service that can be accessed by the client.
A resource has an identifier - URI (Uniform Resource Identifier) - that uniquely identifies that resource.
Clients interact with a service by exchanging representations of resources. Many web APIs use JSON to exchange the format
REST APIs use a uniform interface, which decouple the client and service implementations
What does GET do?
GET retrieves a representation of the resource at the specified URI. The body of the response message contains the details of the requested resource.
What does POST do?
POST creates a new resource at the specified URI. The body of the request message provides the details of the new resource. Note that POST can also be used to trigger operations that don’t actually create resources.
What does PUT do?
PUT either creates or replaces the resource at the specified URI. The body of the request message specifies the resource to be created
What does PATCH do?
PATCH performs a partial update of a resource. The request body specifies the set of changes to apply to the resource.
What does DELETE do?
DELETE removes the resource at the specified URI.
Example of what these requests do…
/customers
POST: Create a new customer
GET: retrieve all customers
PUT: Bulk update of customers
DELETE: remove all customers
/customers/1
POST: error
GET: Retrieve the details for customer 1
PUT: Update the details of customer 1, if it exists
DELETE: remove customer
/customers/1/orders
POST: Create a new order for customer 1
GET: retrieve all orders for customer 1
PUT: Bulk update of orders for customer 1
DELETE: remove all orders for customer 1
Where should information be stored?
The only place information should be stored is in the resources themselves, and each request should be an atomic operation.
This constraint enables web services to be highly scalable, because there is no need to retain any affinity between clients and specific servers and thus any server can handle any request from any client.
What is the first level of API maturity?
Level 0: the Swamp of POX
This is the least conforming to REST architecture style. Usually exposes just one URI for the entire application. SOAP or XML-RPC based applications come in at this level. Only uses HTTP POST for all actions, even for data fetch.
POX stands for Plain Old XML
What is the second level of API maturity?
Level 1: Resource based address/URI
These services employ multiple URIs unlike level 0, however they still only use HTTP POST for all operations. Every resource is identifiable by its own unique URI - including nested resources. This resource-based addressing can be considered the starting point for APIs being RESTful.
What is the third level of API maturity?
Level 2: HTTP Verbs
APIs at this level fully utilize all HTTP command or verbs such as GET, POST, PUT and DELETE. The request body doesn’t carry the operation information at this level. The return codes are also properly used so that the clients can check for errors
What is for fourth and final level of API maturity?
Level 3: HyperMedia/HATEOAS
Most mature APIs are at this level. They use HATEOAS (Hypertext as The Engine of Application State). It’s also known as HyperMedia, which basically consists of resource links and forms. Establishing connections between resources becomes easy as they don’t require human intervention and aids client-driven automation.
How do you organise APIs?
Organise the API design around resources by focusing the business entities that the web API exposes. When possible, resource URIs should be based on nouns (the resource) and not verbs (the operations on the resource).
Avoid creating APIs that simply mirror the internal structure of a database, a client should not be exposed to the internal implementation.
Adopt consistent naming conventions in URIs.
Consider the relationships between different types of resources and how you might expose these associations.
Consider load on the server, and avoid “chatty” web APIs that expose a large number of small resources.
What are asynchronous operations?
Sometimes a REST operation might require processing that takes a while to complete, if you wait for completion before sending a response to the client, it might cause unacceptable latency.
If this is the case, consider making the operation asynchronous. Return HTTP status 202 to indicate the request was accepted for processing but is not completed.
