API Best Practices

api-best-practices.markdown

The JSON API Standard

What is the JSON API Standard

The Specification

• The History
• Why does it exist?
  • Bike Shedding/LookingFor
• Do we have to use it?
• What are the important takeaways?

Document Structure

• Spec

Typically implemented through libraries

• List of Implementations

Some Implementations of Note*

• The Original - Ember Data
• Redux JSON API
• Active Model Serializers [Note: said to be a little out of date with the standard]
• JSONapiForRails

Returning Data

• All Status Codes
• Basic Top Level Record Information
• Compund Documents
• Fetching
• CRUD functionality

Pagination

• Spec
• Example
• LookingFor Pagination
• LookingFor Endpoint
• api-pagination gem

Your Turn

• Spend the next ten minutes reading the pagination spec to see if our application meets the JSON api standard.

Error Objects

• Twitter's API Codes
• Spec
• Example

Your Turn

• Look through your Ideabox projects
  • What would you have needed to add to your API to render error messages in your view?

Digging Deeper

• How to Build Rails APIs Following the json:api Spec
• How and Why You Should Use JSON API in your Rails API
• Modern Bridge Ember and Rails 5 with JSON API
• JSONAPI::Resources