Building APIs that DON'T SUCK !

Neo Ighodaro CTO, Hotels.ng Ambassador, Auth0 Technical Writer, Pusher Twitter/GitHub: @neoighodaro Website: neoighodaro.com

What we will be considering

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

Database Planning Structure and Content

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.

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.

Endpoints Planning and Creating Endoints

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")

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.

Posts Categories Users Create Create Create Read Read Read Update Update Update Delete Image Image

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

! 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

Responses HTTP Status Codes, Errors and Messages

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/

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/

Responses Data Output Structure

{ "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.

Securing your API from the bahd guys

API Authentication https://auth0.com/docs/api-auth

Working with scopes http://docs.apigee.com/api-services/content/working-scopes

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

Thank You The slides go SKRRRRAAAAA! Slide is available at https://bit.ly/building-apis-that-dont-suck