Designing Restful APIs
@skorfmann
Let's Build an API
"Hey, we will need an api!"
-
"Alright, brb - I'm gonna build you something"
YOU'RE DOING IT WRONG!
API Design Process
- Research
- Design
- Client (Mock Endpoint)
-
Actual Implementation
Research
- Audience
-
Goals
Design
- Standards
- Documentation
- Feedback
Standards
Existing Standards
- JSON API
- HAL
- Siren
- Hyper JSON
- ...
Documentation
-
API Blueprint
-
Slate
-
Swagger
API Blueprint
- Markdown
- Custom Extensions
- API Mocks
- Tools
Blueprint Markdown
+ Request JSON Message + Headers Accept: application/json + Response 200 (application/json) + Body { "message": "Hello World!" }
Blueprint Markdown
+ Parameters + id (number, `1`)
Blueprint Tools
- API Mock
- Dredd (Test Your Documentation)
-
Aglio (Generate Static Website)
Apiary.io
-
Host API Blueprints
-
Code Examples
-
API Mock Endpoint
Client Implementation
- Self-Contained
-
Mock Endpoint
Ember Data
Client Libraries
- Mock Endpoint
-
Test Mode
Last But Not Least
- Expected Errors
- Exceptions
-
Testable Examples (Stripe)