Downloaded 200 times
![Status Codes
• 200 OK – [GET/PUT/PATCH] The Consumer requested data from the
Server, and the Server found it for them (Idempotent)
• 201 CREATED – [POST] The Consumer gave the Server data, and the
Server created a resource
• 204 NO CONTENT – [DELETE] The Consumer asked the Server to delete
a Resource, and the Server deleted it
• 400 BAD REQUEST – [POST/PUT/PATCH] The Consumer gave bad data
to the Server, and the Server did nothing with it (Idempotent)
• 404 NOT FOUND – [GET/PUT/PATCH/DELETE] The Consumer
referenced a nonexistent Resource or Collection, and the Server did
nothing (Idempotent)
• 500 INTERNAL SERVER ERROR – [*] The Server encountered an error,
and the Consumer has no knowledge if the request was successful](https://image.slidesharecdn.com/restfulapibestpractices-170110160001/85/RESTful-API-Best-Practices-12-320.jpg)
![Status Codes
• 200 OK – [GET/PUT/PATCH] The Consumer requested data from the
Server, and the Server found it for them (Idempotent)
• 201 CREATED – [POST] The Consumer gave the Server data, and the
Server created a resource
• 204 NO CONTENT – [DELETE] The Consumer asked the Server to delete
a Resource, and the Server deleted it
• 400 BAD REQUEST – [POST/PUT/PATCH] The Consumer gave bad data
to the Server, and the Server did nothing with it (Idempotent)
• 404 NOT FOUND – [GET/PUT/PATCH/DELETE] The Consumer
referenced a nonexistent Resource or Collection, and the Server did
nothing (Idempotent)
• 500 INTERNAL SERVER ERROR – [*] The Server encountered an error,
and the Consumer has no knowledge if the request was successful](https://image.slidesharecdn.com/restfulapibestpractices-170110160001/75/RESTful-API-Best-Practices-12-2048.jpg)
Uploaded byTricode (part of Dept)
RESTful API - Best Practices
The document outlines best practices for building RESTful APIs, emphasizing the importance of good design, data abstraction, and security. It covers key components such as HTTP verbs, endpoints, response status codes, content types, versioning, and the necessity of documentation. The presentation aims to provide a comprehensive guide for developers to create effective and user-friendly APIs.
In this document
Powered by AI
Introduction of Tricode BV and the topic of Best Practices on Building RESTful API by Nikola Vasilev.
The agenda summarizes the topics covered in the presentation, including data design, security, and documentation.
Definition of REST and RESTful APIs; emphasizes the challenges of good RESTful API design.
Focus on API-first development, avoiding complete functionality exposure, and strategic connection to existing projects.
Descriptions of key HTTP verbs: GET, POST, PUT, PATCH, DELETE; defining their respective roles in API operations.
Stresses the significance of a simple and clear API Root URL with examples of best practices.
Guidelines for constructing endpoints using plural nouns, avoiding verbs, and practical examples of CRUD actions.
Expected responses based on actions, appropriate status codes, and examples of content types like JSON and XML.
The necessity of versioning in APIs, ensuring old versions remain accessible while introducing new ones.
Recommendations for securing APIs, including token usage and OAuth2 for authentication.
The essential role of comprehensive documentation to aid user understanding and accessibility of the API.
Sources for additional reading on RESTful API design principles, including blogs and eBooks.
Social media and contact information for Tricode BV to encourage further engagement.
More Related Content
Similar to RESTful API - Best Practices
![UiPath Automation Suite Installation (Hands-On) [2/3]](https://cdn.slidesharecdn.com/ss_thumbnails/automationsuitecommunitysession2-251015095633-a6d862f1-thumbnail.jpg?width=600ounds&width=560&fit=bounds)
RESTful API - Best Practices
- 1. Tricode BV De Schutterij12 -18 3905 PL Veenendaal The Netherlands tel: 0318 - 559210 fax: 0318 - 650909 www.tricode.nl info@tricode.nl Best Practices on Building RESTful API Nikola Vasilev Thursday, 1st of December 2016
- 2. Agenda • Introduction • DataDesign and Abstraction • Verbs • Endpoints • Request • Response • Demo • Security • Documentation • References 2
- 4. Introduction • What isREST? • What is a RESTful API? 4
- 5. Introduction • Good RESTfulAPI design is hard! • Language Agnostic Approach 5
- 6. Data Design and Abstraction •API First Development • Attaching an API to an existing project • Don’t expose the whole functionality via API 6
- 7. Verbs • GET (SELECT):Retrieve a specific Resource from the Server, or a listing of Resources. • POST (CREATE): Create a new Resource on the Server. • PUT (UPDATE): Update a Resource on the Server, providing the entire Resource. • PATCH (UPDATE): Update a Resource on the Server, providing only changed attributes. • DELETE (DELETE): Remove a Resource from the Server. 7
- 8. API Root URL •The root location of your API is important. • The API Root URL needs to be as simple as possible: • Provide a list of all endpoints on the root url. • Simple endpoints: – https://api.github.com/ – https://graph.facebook.com – https://api.example.com/v1 – https://yourproduct.com/api/v2 8
- 9. Endpoints • Use pluralnouns: – https://api.example.com/v1/employees – https://api.example.com/v1/departments – https://api.example.com/v1/employees • Use uniform endpoint for each functionality • Don’t use verbs: – https://api.example.com/v1/add_employee – https://api.example.com/v1/edit_employee – https://api.example.com/v1/delete_employee 9
- 10. Endpoints (2) • GET/employees: List all Employees (ID and Name, not too much detail) • POST /employees: Create a new Employee • GET /employees/EID: Retrieve an entire Employee object • PUT /employees/EID: Update an Employee (entire object) • PATCH /employees/EID: Update an Employee (partial object) • DELETE /employees/EID: Delete an Employee 10
- 11. Response • GET /employees:Return a listing (array) of Employees • GET /employees/EID: Return an individual Employee • POST /employees: Return the newly created Employee • PUT /employees/EID: Return the complete Employee • PATCH /employees/EID: Return the complete Employee • DELETE /employees/EID: Return an empty document
- 12. Status Codes • 200OK – [GET/PUT/PATCH] The Consumer requested data from the Server, and the Server found it for them (Idempotent) • 201 CREATED – [POST] The Consumer gave the Server data, and the Server created a resource • 204 NO CONTENT – [DELETE] The Consumer asked the Server to delete a Resource, and the Server deleted it • 400 BAD REQUEST – [POST/PUT/PATCH] The Consumer gave bad data to the Server, and the Server did nothing with it (Idempotent) • 404 NOT FOUND – [GET/PUT/PATCH/DELETE] The Consumer referenced a nonexistent Resource or Collection, and the Server did nothing (Idempotent) • 500 INTERNAL SERVER ERROR – [*] The Server encountered an error, and the Consumer has no knowledge if the request was successful
- 13. Content Type • JSON { "id":12, "firstName": "John", "lastName": "Doe", "dateOfBirth": "1987-12-26", } • XML <?xml version="1.0 encoding="UTF-8"?> <employee> <id>12</id> <firstName>John</fristName> <lastName>Doe</lastName> <dateOfBirth>1987-12-28</dateOfBirth> </employee>
- 14.
- 15. Versioning • No matterhow the API has been built. It will be change by time. • A good mechanism for versioning the API should be introduced. • The old version for the existing customers needs to be kept. • The new customers will implement the new version. • Introduce deprecation notice of your api – https://api.yourdomain.com/v1 – https://api.yourdomaincom/v2 15
- 16. Authentication • Secure yourAPI • Build a customer token and use Basic Authorization over SSL • OAuth2
- 17. Documentation • No Documentation?- No one will know how to use your API. • Make the documentation available publicly (Google needs to know about it) • Document each endpoint, with each action, every response possible. • Build developer API console if possible.
- 18. References • Blog: https://codeplanet.io/principles-good-restful-api-design/ •Ebook: https://github.com/tlhunter/consumer-centric-api-design • Hardcopy: https://www.amazon.com/Consumer-Centric-API-Design- Thomas-Hunter/dp/136498900X/
- 20.