Service Oriented Computing

Akshaya Ganesan
Assistant Professor[Off-Campus]
BITS-Pilani
Precap

• REST architectural style

• REST constraints
• Uniform interface
• Connectedness
• Addressability
Agenda

• Identifier Design with URIs

• Interaction Design with HTTP(response codes, request methods)
• Metadata Design(Media Types, content negotiation)
• Representation Design(Message body format, Hypermedia Representation)
 REST API Design
API design is more of an art
• Some best practices for REST API design are implicit in the HTTP standard,
• When should URI path segments be named with plural nouns?
• Which request method should be used to update resource state?
• How do I map non-CRUD operations to my URIs?
• What is the appropriate HTTP response status code for a given scenario?
• How can I manage the versions of a resource’s state representations?
• How should I structure a hyperlink in JSON?
 API Design Elements
The following aspects of API design are all important, and together they define your API:
• The representations of your resources and the links to related resources.
• The use of standard (and occasionally custom) HTTP headers.
• The URLs and URI templates define your API’s query interface for locating resources based on
their data.
• Required behaviors by clients—for example, DNS caching behaviors, retry behaviors

• Representation Design(Message body format, Hypermedia Representation)

• Interaction Design with HTTP(response codes, request methods)
• Metadata Design(Media Types, content negotiation)
• Identifier Design with URIs
 Identifier Design
REST APIs use Uniform Resource Identifiers (URIs) to address resources
• URI Format
• URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

• Forward slash separator (/) must be used to indicate a hierarchical relationship

• Consistent subdomain names should be used for your APIs
 Identifier Design

Resource Modelling

• The URI path conveys a REST API’s resource model,

• Each forward slash-separated path segment corresponds to a unique resource within the model’s hierarchy.
• http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet
• http://api.soccer.restapi.org/leagues/seattle/teams
• http://api.soccer.restapi.org/leagues/seattle
• http://api.soccer.restapi.org/leagues
• http://api.soccer.restapi.org Few antipatterns

• document, GET /deleteUser?id=1234

• http://api.soccer.restapi.org/leagues/seattle GET /deleteUser/1234
• http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet
DELETE /deleteUser/1234
• collection,
• Each URI below identifies a collection resource:
POST /users/1234/delete
• http://api.soccer.restapi.org/leagues
• http://api.soccer.restapi.org/leagues/seattle/teams
• controller.
• POST /alerts/245743/resend
 Identifier Design
URI Path Design
• Rule: A singular noun should be used for document names
• Rule: A plural noun should be used for collection names
• Rule: A verb or verb phrase should be used for controller names
• Rule: Variable path segments may be substituted with identity-based values
• http://api.soccer.restapi.org/leagues/{leagueId}/teams/{teamId}/players/{playerId}
• Rule: CRUD function names should not be used in URIs
 Identifier Design
URI Query Design
• As a component of a URI, the query contributes to the unique identification of a resource.
• Rule: The query component of a URI may be used to filter collections
• Rule: The query component of a URI should be used to paginate collections
• Represent relationships clearly in the URI
 Interaction Design
Interaction Design with HTTP

• REST APIs embrace all aspects of the HyperText Transfer Protocol including its request
methods, response codes, and message headers

• Each HTTP method has specific, well-defined semantics within the context of a REST API’s
resource model.
• The purpose of GET is to retrieve a representation of a resource’s state.
• HEAD is used to retrieve the metadata associated with the resource’s state.
• PUT should be used to add a new resource to a store or update a resource.
• DELETE removes a resource from its parent.
• POST should be used to create a new resource within a collection and execute controllers.
 Interaction Design
Interaction Design with HTTP
• Rule: GET and POST must not be used to tunnel other request methods
• Rule: GET must be used to retrieve a representation of a resource
• Rule: HEAD should be used to retrieve response headers
• Rule: PUT must be used to both insert and update a stored resource
• Rule: PUT must be used to update mutable resources
• Rule: POST must be used to create a new resource in a collection
• Rule: POST must be used to execute controllers
• Rule: DELETE must be used to remove a resource from its parent
• Rule: OPTIONS should be used to retrieve metadata that describes a resource’s available interactions
 Interaction Design
HTTP response success code summary
• 200 OK Indicates a nonspecific success
• 201 Created Sent primarily by collections and stores but sometimes also by controllers, to indicate that a new
resource has been created
• 204 No Content Indicates that the body has been intentionally left blank
• 301 Moved Permanently Indicates that a new permanent URI has been assigned to the client’s requested resource
• 303 See Other Sent by controllers to return results that it considers optional
• 401 Unauthorized Sent when the client either provided invalid credentials or forgot to send them
• 402 Forbidden Sent to deny access to a protected resource
• 404 Not Found Sent when the client tried to interact with a URI that the REST API could not map to a resource
• 405 Method Not Allowed Sent when the client tried to interact using an unsupported HTTP method
• 406 Not Acceptable Sent when the client tried to request data in an unsupported media type format
• 500 Internal Server Error Tells the client that the API is having problems of its own
 Metadata Design
Important HTTP headers
Media type negotiation should be supported when
• Content type multiple representations are available
• Content length
• Last-modified
• E-tag
• Location
Representation Design

• Representation is the technical term for the data that is returned

• Users can view the representation of a resource in different formats, called media types
• JSON is the preferred format
• XML and other formats may optionally be used for resource representation
• A consistent form should be used to represent media types, links and errors
Best Practices

Use only nouns for a URI;

GET methods should not alter the state of resource;
Use plural nouns for a URI;
Use sub-resources for relationships between resources;
Use HTTP headers to specify input/output format;
Provide users with filtering and paging for collections;
Version the API;
Provide proper HTTP status codes.
Resource Design

• 1. Figure out the data set

• 2. Split the data set into resources
• For each kind of resource:
• 3. Name the resources with URIs
• 4. Expose a subset of the uniform interface
• 5. Design the representation(s) accepted from the client
• 6. Design the representation(s) served to the client
• 7. Integrate this resource into existing resources, using hypermedia links and forms
• 8. Consider the typical course of events: what’s supposed to happen?
• 9. Consider error conditions: what might go wrong?
Self Reading

• https://learn.microsoft.com/nl-nl/azure/architecture/best-practices/api-design
References

1) Restful Web services, Leonard Richardson and Sam Ruby, 1 st edition published by O'Reilly
Media,
2) REST API Design Rulebook by Mark Massé
Thank You!
In our next session: