What is REST?
REST is an acronym for "Representational State Transfer".
REST is a mechanism for using standard HTTP concepts to access machine readable resources. REST allows programmers to access web APIs with very little overhead.
A well-written REST API is easily understandable, readily consumable and self-documenting.
What does REST look like?
● Resource-Oriented
○ /v1/customers - a collection of or search for customers
○ /v1/customers/{} - a specific customer
● HTTP Verb Driven
○ GET - fetch / search
○ POST - create
○ PUT/PATCH - update
○ DELETE - remove
Why REST?
● Well understood in the industry
● Easily implementable
● Easily consumable
● Lifecycle tools
● Governance tools
Benefits of Resource-Oriented, Verb-Driven APIs
● Clear intent, common understanding
● HTTP caching tricks enabled ○ ETag ○ If-Modified-Since ○ Cache-Control
● Security, Logging, Analytics & more orthogonal to protoco
PUT vs PATCH
● Both verbs update an existing entity
● PATCH should change only mentioned fields, and null should remove a field
● PUT should completely replace the entity with provided payload
Best Practice: Sweep Complexity Behind the ' ? ' Relationships can be complex. Use query parameters instead of complex pathing.
● Which would you rather use?
● Which is more performant in bandwidth and compute constrained client environments?
Response codes should communicate only what the developer consuming an API needs It's not uncommon for a response code or message to accidentally divulge proprietary details from internal systems. Remember that response codes will be consumed by untrusted actors, and should communicate only what the developer needs to know to either correct the issue or alert the user, but no more.
Seven Minimal Error Codes
● 200
● 201
● 304
● 400
● 401
● 404
● 500
Seven Minimal Error Codes
● 200 OK Resource found, accessible and available. Action taken and response in payload.
● 201 Created Resource was created; payload contains new object (or reference to).
● 304 Not Modified No change since last request. Use cached copy.
● 400 Bad Request Request was missing required elements. Repair and resubmit.
● 401 Unauthorized User has not obtained any token. Include authorization instructions in return body.
● 404 Not Found No such resource accessible to current client / user.
When should pagination be used?
When to use pagination:
● A large number of results in a list.
● An unknown number of results in a list.
● Results are of the same resource type.
● Queries or listings.
When not to use pagination:
● When the payload is not a list of objects.
● Small, known number of results never to exceed a handful (e.g. 5-10)
● 500 Server Error Something went wrong behind
Best Practice for Pagination.
Paged resources should have a metadata section that describes, at a minimum, the current page, the number of resources requested, and the number of resources in the current page listing.
A Helpful Idea Include a URL for the next/previous page, so the developer intuitively knows how to fetch them
Best Practice for Pagination. The item list need not be the full item. Instead, consider what summary information is required for use & display. Include that, plus a link to the full item.
REST is an acronym for "Representational State Transfer".
REST is a mechanism for using standard HTTP concepts to access machine readable resources. REST allows programmers to access web APIs with very little overhead.
A well-written REST API is easily understandable, readily consumable and self-documenting.
What does REST look like?
● Resource-Oriented
○ /v1/customers - a collection of or search for customers
○ /v1/customers/{} - a specific customer
● HTTP Verb Driven
○ GET - fetch / search
○ POST - create
○ PUT/PATCH - update
○ DELETE - remove
Why REST?
● Well understood in the industry
● Easily implementable
● Easily consumable
● Lifecycle tools
● Governance tools
Benefits of Resource-Oriented, Verb-Driven APIs
● Clear intent, common understanding
● HTTP caching tricks enabled ○ ETag ○ If-Modified-Since ○ Cache-Control
● Security, Logging, Analytics & more orthogonal to protoco
PUT vs PATCH
● Both verbs update an existing entity
● PATCH should change only mentioned fields, and null should remove a field
● PUT should completely replace the entity with provided payload
Best Practice: Sweep Complexity Behind the ' ? ' Relationships can be complex. Use query parameters instead of complex pathing.
● Which would you rather use?
● Which is more performant in bandwidth and compute constrained client environments?
Response codes should communicate only what the developer consuming an API needs It's not uncommon for a response code or message to accidentally divulge proprietary details from internal systems. Remember that response codes will be consumed by untrusted actors, and should communicate only what the developer needs to know to either correct the issue or alert the user, but no more.
Seven Minimal Error Codes
● 200
● 201
● 304
● 400
● 401
● 404
● 500
Seven Minimal Error Codes
● 200 OK Resource found, accessible and available. Action taken and response in payload.
● 201 Created Resource was created; payload contains new object (or reference to).
● 304 Not Modified No change since last request. Use cached copy.
● 400 Bad Request Request was missing required elements. Repair and resubmit.
● 401 Unauthorized User has not obtained any token. Include authorization instructions in return body.
● 404 Not Found No such resource accessible to current client / user.
When should pagination be used?
When to use pagination:
● A large number of results in a list.
● An unknown number of results in a list.
● Results are of the same resource type.
● Queries or listings.
When not to use pagination:
● When the payload is not a list of objects.
● Small, known number of results never to exceed a handful (e.g. 5-10)
● 500 Server Error Something went wrong behind
Best Practice for Pagination.
Paged resources should have a metadata section that describes, at a minimum, the current page, the number of resources requested, and the number of resources in the current page listing.
A Helpful Idea Include a URL for the next/previous page, so the developer intuitively knows how to fetch them
Best Practice for Pagination. The item list need not be the full item. Instead, consider what summary information is required for use & display. Include that, plus a link to the full item.
ليست هناك تعليقات:
إرسال تعليق