building-apis-that-dont-suck

The session slides on "Building API's that don't suck" by Neo Ighodaro during the ANC Developing Android Developers Meetup

Transcript

1. Building APIs that DON'T SUCK !
2. Neo Ighodaro CTO, Hotels.ng Ambassador, Auth0 Technical Writer, Pusher Twitter/GitHub: @neoighodaro Website: neoighodaro.com
3. What we will be considering
4. 4 Database – Planning Structure and Content 4 Endpoints – Planning and Creating 4 Responses 4 HTTP Status Codes, Errors and Messages 4 Data Output Structure 4 Security and Controlled Access 4 Other Considerations
5. Database Planning Structure and Content
6. Database Tables & Seeding Your tables should reflect the resources you wish to have and it is very dependent on the features of your application. For instance, building an Android book store might have resources like: users, books, book_categories, book_downloads etc.
7. Database Tables & Seeding Seeding is basically adding mock data to your database so you can run tests and have data returned. Seeds are NOT meant to be used in production. You can use libraries that generate fake data to create fake data for each column in your database table.
8. Endpoints Planning and Creating Endoints
9. Functional Requirements Think through everything your API will need to handle. This usually starts out with the resources and the CRUD (Create, Read, Update, Delete) operations for them. List each resource out (a resource can be "books" or "places" or "articles")
10. Functional Requirements Gradually dive deeper into each resource and see if it needs additional methods or additional parameters. For instance, you might have a "books" resource and you want a cool feature like "Favorite Book". Those things need to be planned also.
11. Posts Categories Users Create Create Create Read Read Read Update Update Update Delete Image Image
12. Creating Endpoint From Resources You can turn the resources you created to generate endpoints that respond to different HTTP verbs. You will need a little knowledge on RESTful APIs and “best practices” for naming conventions. hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9
13. ! Useful Tip! Use GET for read operations, POST for create operations, DELETE for delete operations and PUT for update operations. hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9
14. Responses HTTP Status Codes, Errors and Messages
15. HTTP Status Codes Your HTTP status code should be proper and match what you are trying to tell the client. For instance, when a resource is not found, a 404 - Not Found status code must be passed to the client. When a resource is created, you can pass a 201 - Created. https://restfulapi.net/http-status-codes/
16. Errors and Messages Apart from sending the right HTTP status code, your errors and success messages should be descriptive enough to know what is going on. https://restfulapi.net/http-status-codes/
17. Responses Data Output Structure
18. { "data": { "id": 123456 "name": "Neo Ighodaro", "comments": { "data": [ { "id": 1234 "text": "The tin go skraaaa..." }, { "id": 1234 "text": "Pa pa ka ka ka..." } ] } } } http://jsonapi.org/format/ By using a standard, you will always have consistent response across endpoints. No surprises.
19. Securing your API from the bahd guys
20. API Authentication https://auth0.com/docs/api-auth
21. Working with scopes http://docs.apigee.com/api-services/content/working-scopes
22. Other Considerations Always Write Unit Tests Return error messages as codes e.g BOOK_NOT_FOUND Document API with tools like Swagger.io Employ Caching with tools like Varnish
23. Thank You The slides go SKRRRRAAAAA! Slide is available at https://bit.ly/building-apis-that-dont-suck