• Understand REST principles
• Understand connectedness and/or hypermedia
• Design a small API
• Write API documentation

You have two options:

1. Implement the API using a non-hypermedia format (RESTful CRUD). In this case, it is mandatory that all your resources are connected. You cannot get full points in this section if you do not design your API using an hypermedia format
2. Using an hypermedia format. Lots of examples provided in Exercise 3. You can get full points. In this case you need to clearly include in the documentation a profile with link relations and semantic descriptors.

The recommended step-by-step process  is:

1. Identify all the resources to be exposed by the Web API. To that end, students should make an abstraction of the concepts defined in section 1. Be aware that a one-to-one mapping between the resources and the concepts defined in section 1 is not usually the best option. Sometimes it is better to pack several concepts in the same resource.
2. Establish the resource hierarchy and assign a URI to each resource.
3. Establish relations and possible actions among resources. Create the state diagram of your API.
4. Expose each one of the resources to the uniform interface.
5. Design the resource representation using adequate format.
   
   1. Define the media type and its extension (if any)
   2. Define the profiles (if you are using an hypermedia format). Try to reuse existing profiles as much as possible. For instance, utilize schemas defined in schemas.org.
   3. Do not forget to include the format of the requests. If you are using hypermedia format and the media type does not define the format of the requests, they must be defined in the profile. Otherwise, the request formats must be defined in the documentation.

1. Fill the table below with a description of the API resources
2. Include a state diagram of your application, in which each resource is a state. Describe also the state transitions. To build this diagram you should reuse the diagram created in DL1. You can use online tools such as draw.io or lucidchart to create the diagrams. You have an example in the following image

• Resource table with URLs and short descriptions is provided: 0.5
• State diagram with transitions exists (see below): 0.5
• State diagram follows relationships from DL1: 0.5
• State diagram is correct, states make sense, transitions are clear and all possible transitions documented: 1.0

• The uniform interface shows all possible requests and actions are described for each: 1.0

Use any of the tools presented in Exercise 2 and 3 (e.g. Apiary) to document the API. Follow the format specified in that exercise also. You can take the Paypal REST API or TVflix service REST API (created by previous year students) as a model.

For all resources you must cover:

• The possible HTTP methods exposed by this resource
• The headers in the request and responses
• The media type utilized (in the response Content-Type header). If you are utilizing your own media-type you must describe it in the section Own media type implementation.
• If you are using an hypermedia type you must provide the profile utilized, including.
  • Link relations. Include methods and format of the requests if they are defined in the media type. Use as much as possible IANA defined relations.
  • Semantic descriptors. If you utilize a descriptor used in some other profile (e.g. schema.org) provide the link.
  • If you are extending other profiles, do not forget to link to the extended profile.
• The format of the HTTP response body, providing a clear example. If necessary, comment the example.
• The format of the HTTP request body (just for PUT/POST), providing a clear example. If necessary, comment the example.
• The error conditions, status code and format of the error response, providing a clear example.

• You are using a hypermedia API: 3.0
• Each request has the correct media type: 0.5
• The media type is used according to its specification: 1.5
• Link relations are described (either in the profile for hypermedia types, or in the resource documentation for the CRUD approach): 1.0
  • Do not forget you can use link relations from http://www.iana.org/assignments/link-relations/link-relations.xhtml
• Attributes are clearly explained ( either in the profile - for hypermedia types - or in the resource documentation - for the CRUD approach -): 1.0
• Examples are provided for each request: 0.5
• Examples provided for each request do not contain errors: 0.5
• Examples are provided for each response: 1.0
• Examples provided for each response do not contain errors: 1.0
• Examples includes error responses 0.25
• Examples provided in error responses do not contain errors 0.25
• Examples have correct headers: 0.5
• Profiles are linked in each response (only for hypermedia APIs, CRUD implementation receive 0 points in this section): 0.5
• Examples use correct status codes: 1.0
• Design is coherent: 1.0

• The justification is clear and coherent, and shows an understanding of REST principles: 2.0
• The Api is addressable (no errors regarding addressability): 1.0
• The Api uses correctly the uniform interface: 1.0
• The Api does not hold state in the server: 0.5
• The different resources of the API are connected, that is there are not isolated resources: 2.0
  • isolated resource is a resource that either is not linked to from anywhere, or doesn't contain links itself
• Protocol semantics are clearly provided either by the response or by the profile (If you are using a CRUD API you won't get points in this section): 1.5