The document discusses API design principles for RESTful APIs, including defining URI endpoints, request methods, headers and message bodies, and response status codes. It also covers API documentation tools like Swagger and logging frameworks like Logback. Finally, it provides an assignment on implementing a RESTful API for user authentication and administration that follows best practices, uses logging, and exposes API documentation.

1. API Design
William Huan Le

2. API Design
● API (Application Programming Interface)
○ API is a software interface that allows two applications to
interact with each other
○ API provides product or service to communicate with other
products and services without having to know how they’re
implemented
○ Restful API
● API document
○ Swagger
● Log
○ Log4j
○ Logback

3. Restful API
● RESTful API is built on REST’s architecture and principles
● RESTful API is an architectural style that uses HTTP requests to access and use data

4. Restful API design
1. Request API endpoint (URI):
○ https://mybusiness.googleapis.com/v4/accounts/{accountId}/loca
tions/{locationId}/localPosts
2. Request Methods
○ GET/ PUT/ POST/ DELETE/ …
3. Request/Response Headers
4. Request/Response Message body
5. Response HTTP Status Code

5. Restful API design API endpoint (URI)
URI format:
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}/localPosts
1. Slash (/) must be used to indicate a hierarchical relationship, forward slash (/) should not be included in URIs
2. Hyphens (-) should be used to improve the readability of URIs
3. Underscores (_) should not be used in URIs
4. Lowercase letters should be preferred in URI paths
5. File extensions should not be included in URIs

6. Restful API design API endpoint (URI)
URI Authority:
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}/localPosts
1. Consistent subdomain names should be used for your APIs
2. Consistent subdomain names should be used for your client developer portal

7. Restful API design API endpoint (URI)
Path design:
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}/localPosts
1. A singular noun should be used for document names
2. A plural noun should be used for collection names
3. A plural noun should be used for store names
4. A verb or verb phrase should be used for controller names
5. Variable path segments may be substituted with identity-based values
6. CRUD function names should not be used in URIs

8. Restful API design API endpoint (URI)
URI Query Design
1. The query component of a URI may be used to filter collections or stores
2. The query component of a URI should be used to paginate collection or store results

9. Restful API design Request Methods
1. GET must be used to retrieve a representation of a resource
2. HEAD should be used to retrieve response headers
3. PUT must be used to both insert and update a stored resource
4. POST must be used to create a new resource in a collection
5. DELETE must be used to remove a resource from its parent

10. Restful API design Request/ response Headers
● Content-Type must be used
○ Content-Type Identifies the entity body’s
media type
● Content-Length should be used
○ The size (in bytes) of the entity body

11. Restful API design Request/ response Message Body
1. Message Body Format
a. JSON should be supported for resource representation
b. JSON must be well-formed

12. Restful API design Response HTTP Status Code
Ranges
1. 1xx: Informational Communicates transfer protocol-level information.
2. 2xx: Success Indicates that the client’s request was accepted
successfully.
3. 3xx: Redirection Indicates that the client must take some additional
action in order to complete their request.
4. 4xx: Client Error This category of error status codes points the finger at
clients.
5. 5xx: Server Error The server takes responsibility for these error status
codes
Ref:
1. https://developers.google.com/search/docs/crawling-indexing/http-network-errors
2. https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200

13. Swagger
What is an API Documentation/
Specification/ Definition?
an API specification explains how
the API behaves and what to expect
from the API

14. Swagger
● Swagger UI
https://www.baeldung.com/swagger-2
-documentation-for-spring-rest-api
● Editor
https://editor.swagger.io/

15. Logback
https://www.baeldung.com/spring-boot-logging

16. Assignment
1. What is web service? REST? SOAP? Restful?
2. What are the advantages and disadvantages of rest api, web service?
3. Swagger editor (schema format, define api, define object)
4. Logback
5. Use restful principle to implement API use restful principle
5.1. Login ADMIN/ USER role
5.2. ADMIN: CRUD (create, read, update, delete)
5.3. USER: read only (get all, get detail)
5.4. Use logback to log request/ response
5.5. Expose API Swagger Document