Scribd
Upload
17 views14 pages

CS6 - APIDesign Continued

The document discusses Service Oriented Computing, focusing on identifier design with URIs, interaction design with HTTP, and metadata design. It emphasizes the importance of representation design, content negotiation, and best practices for identifying resources in RESTful web services. Key concepts include using JSON for data representation, server-driven and agent-driven content negotiation, and the significance of resource modeling.

Uploaded by

mohit
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
17 views14 pages

CS6 - APIDesign Continued

The document discusses Service Oriented Computing, focusing on identifier design with URIs, interaction design with HTTP, and metadata design. It emphasizes the importance of representation design, content negotiation, and best practices for identifying resources in RESTful web services. Key concepts include using JSON for data representation, server-driven and agent-driven content negotiation, and the significance of resource modeling.

Uploaded by

mohit
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/ 14

Service Oriented Computing

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

• Identifier Design with URIs


• Interaction Design with HTTP(response codes, request methods)
• Metadata Design(Media Types, content negotiation)
Agenda

• Representation Design(Message body format, Hypermedia Representation)


• Content Negotiation
• Identifying resources
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

• Designing a representation involves


• (a) using that envelope format to include the right headers,
• (b) when there is a body for the representation, choosing a media type and designing a format for the
body

• For a) use Entity headers


Representation Design
How to Choose a Representation Format and a Media Type
• Keep the choice of media types and formats flexible to allow for varying application use cases, and client needs for
each resource.
• Prefer to use well-known media types for representations.
• What data to include in JSON-formatted representations
• An example of a representation of a person resource:
• {
• "name" : "John",
• "id" : "urn:example:user:1234",
• "link" : {
• "rel : "self",
• "href" : "http://www.example.org/person/john"
• },
• "address" : {
• "id" : "urn:example:address:4567",
• "link" : {
• "rel : "self",
• "href" : "http://www.example.org/person/john/address"
• }
Content Negotiation

• Content negotiation is the process of selecting the best representation of a resource for a client
when there are multiple representations (or variants) available
• HTTP specifies two types of content negotiation.
• These are server-driven negotiation and agent-driven negotiation.
• Server-driven negotiation uses request headers to select a variant.
• Agent-driven negotiation uses a distinct URI for each variant.
Content Negotiation
Server Driven
• # Request headers
• Accept: application/atom+xml;q=1.0, application/xml;q=0.6, */*;q=0.0
• Accept-Language: fr;q=1.0, en;q=0.5
• Accept-Encoding: gzip
Content Negotiation
Agent Driven

Image source: Mozilla developer network


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.
Identifying Resources

• One of the first steps in developing a RESTful web service is designing the resource model.
• There is no right or wrong resource model.

• Identify Resources from Domain model


• Bluntly mapping domain entities into resources may lead to inefficient resources.

• How can you determine nouns that are candidate resources?

• Think from a client perspective


• The following factors influence resource granularity:
• Cacheablility
• Frequency of change
• Mutability
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:

You might also like