RESTful API design - GoJamie/PWP GitHub Wiki

Important information for Deadline 3

‼️  This chapter should be completed by Deadline 3 (see course information at Lovelace)

📑  Chapter summary In this chapter, the students must design the RESTful API.The minimum requirements are summarized in the Minimum Requirements section of the Project Work Assignment. Note that if you do not meet Minimum Requirements this section wont be evaluated.

SECTION GOALS:

  • 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.
  • Define protocol attributes: headers, possible response codes ... must be clearly specified both for requests and responses.
  • Define the error conditions. When errors are triggered?
    • Define the format of each HTTP error response, including message body, status code and headers. 
    • It is recommended to use a hypermedia type for the response. This blog post contains some good recommendations.
    • ✔️     Chapter evaluation (max 25 points) You can get a maximum of 25 points after completing this section. More detailed evaluation is provided after each heading.

    RESTful API design

    Resources and relations

    📑  Content that must be included in the section
    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
    ✔️     Evaluation criteria(max 2.5 points) You can get a maximum of 2.5 points after completing this section.
    • 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

    ✏️ This table might serve you as a guide

    Resource name Resource url Resource description
    users api/users/ Get all the users in the system
    events api/events/ Get all the events in the system
    user item api/users/{user}/ Get the user
    events by user api/users/{user}/events/ Get all events by user
    event by user api/users/{user}/events/{event}/ Get event by user
    users by event api/events/{event}/users/ Get all users in event
    event item api/events/{event}/ Get the event

    ✏️ Draw here your state machine diagram State machine diagram

    Uniform interface

    📑  Content that must be included in the section Fill the following table with a description of how your resources are exposed to the uniform interface (GET, PUT/PATCH, POST and DELETE methods). You must describe the action executed in each request. For example, a GET request to the URL /messages/{message_id} "gets the body and the title of a specific message".
    ✔️     Evaluation criteria(max 1 point) You can get a maximum of 1 points after completing this section.
    • The uniform interface shows all possible requests and actions are described for each: 1.0

    ✏️ This table might serve you as a guide

    GET PUT PATCH POST DELETE
    users X X
    events X
    user item X X X
    events by user X
    event by user X X X X
    users by event X X
    event item X

    ✏️ Do not forget to include the sequence diagram Sequence diagram

    API design

    📑  Content that must be included in the section

    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.
    ✔️     Evaluation criteria(max 13.5 points) You can get a maximum of 13.5 points in this section:
    • 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
    • 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

    ✏️ https://eventhuboulu.docs.apiary.io/#

    REST conformance

    📑  Content that must be included in the section Explain briefly how your API meets REST principles. Focus specially in the four principles: Addressability, Uniform interface, Connectedness, Statlessness
    ✔️     Evaluation criteria(max 8 points) You can get a maximum of 8 points in this section:
    • 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

    ✏️ Write here your text

    In our Event API, we think our API meets REST principles.

    Addressability: The access of resource is by url. The url for each resourse has been shown as the first table. For example, we can access resourse user item by api/users/{user}/. If we want access the information of user whose id is 123, we can get it from the url api/users/123/.

    Uniform interface: We have the same interface for ios system, andrid system and windows. At first, for the modification of resourses, we can add action GET/PUT/POST/DELETE in HTTP protocol. And then, we transfer text through JSON format. Finally, we use HTTP Status Code to transfer statement of server. For example, we use the code 200 to represent success.

    Connectedness: For each resource, we can get it by others. All resources are connected together, no resources are isolated. For example, we can find all event collection and information of event item by users.

    Statlessness: In our API, we never store users' state in our session and our API has a separate interface. When user sends a request, the request should include the statement of itself. It means we can use different server to solve the request of each user when we get a new request. All the requested URLs are sufficient to be served without depending on previous requests. That's statelessness in our API.

    Resources allocation

    Task Student Estimated time
    API design bangju wang 8 hours
    REST conformance Hao Ban 8 hours
    Resources and relations Nechir 8 hours
    ⚠️ **GitHub.com Fallback** ⚠️