Phil Sturgeon Rest API Notes

First Document the API

1. Start with the resources. List all the resources and it's attributes in a text document. Skip defining relationships on the user.
2. Use data structures that can be used in requests and responses. Use JSON API specification in the data structures.
3. Convert the draft document of resources to data structures using API Blueprint syntax.
4. Use apiary.io to document the API using markdown.
5. Use MSON.
6.  You can show success and failure cases by using multiple transactions. Request . Request .

https://philsturgeon.uk/api/2016/11/22/apis-documentation-first/

Mocking APIs with API Blueprint

1. Apiary provides mocking server. No coding needed.
2. If you don't want to pay apiary. You can use drakov.

npm install -g drakov
drakov -f yourapi.apib

3. Use http CLI to test teh response.

http GET http://localhost:3000/products --json

https://philsturgeon.uk/api/2016/12/02/mocking-apis-with-api-blueprint/

Rails Serialization for REST APIs

1. Use active model serializers with json_api adapter.

https://philsturgeon.uk/api/2016/12/11/building-rest-apis-with-rails-basic-serialization/

Keeping API Documentation is Up to Date with Code

1. npm install -g dredd

2. dredd init

3. Use seeds to populate the database.

4. Run the dredd in test environment.

RAILS_ENV=test rake db:drop db:create db:migrate db:seed
dredd

5. Create a Makefile to simplify and run make docs_test.

# Makefile
.PHONY: docs_test
docs_test:
  @echo "Seeding database for documentation testing"
  @RAILS_ENV=test rake db:drop db:create db:migrate db:seed:dredd
  @echo "Running dredd... check logs/dredd.log for more information"
  @RAILS_ENV=test dredd > log/dredd.log && echo "Documentation is all good!"

https://philsturgeon.uk/api/2016/12/21/building-rest-apis-with-rails-documentation-testing/

https://philsturgeon.uk/api/2017/01/03/building-apis-with-rails-handling-errors-nicely/