API Design with Apiary

As presentent on ofmForum.

Transcript

1. API DESIGN WITH APIARY Z – @zdne Apiary.io
2. 4 STAGES OF API MATURITY API as a by- product of building apps API documentation generated from code Design-first API Development API Design Consistency
3. APIARY.IO
4. DESIGN-FIRST
5. API DESCRIPTION • API Blueprint • OpenAPI Specification (Swagger) • Others (RAML, WADL, WSDL, Email, Word document)
6. API BLUEPRINT
7. # User [/user] ## Retrieve [GET] Retrieves the . + Response 200 (application/json) { "name": "John" }
10. API LIFECYCLE
11. Preparation Design Development Delivery Consumption Analysis CLASSIC API LIFECYCLE
12. Preparation Design & Prototype Development Delivery Consumption Analysis API LIFECYCLE WITH APIARY
13. Preparation 1. Define domain semantics 2. Choose architectural style 3. Define a style guide*
14. Design & Prototype 1. Formalize API in an API Description format* 2. Put API Description in a VCS 3. Circulate & Review 4. Apiary Mock Server
15. Develop 1. API Description in the same repository as implementation 2. Test locally 3. Test with Apiary 4. Test in CI
16. Deliver 1. Share VCS repository 2. Share Apiary Documentation 3. Embed Apiary Documentation
17. Consume 1. Apiary Documentation 2. Apiary Mock Server 3. Documentation Console 4. Language Examples 5. Apiary Traffic Inspector 6. Apiary Proxy
18. Analysis
19. BONUS: GOVERNANCE • Design Rules • Style Guides • Better DX through CONSISTENCY
20. BONUS: MSON • Human readable data description • Reusable, format-agnostic data modeling language • Data is your API
21. TRY IT NOW http://apiary.io Q&A @apiaryio
23. MIND SHIFT • Describe resource NOT representation • Define domain semantics • Reuse common semantics • Do NOT focus on technical details • URIs • representations • schema validations
24. API ISN’T… • API is not pretty URLs • API is not HTTP Verbs • API is not CRUD • API is not JSON
25. REST ARCHITECTURAL STYLE • Client–server • Stateless • Cacheable • Layered system • Code on Demand (optional) • Uniform Interface • Identification of resources • Manipulation through representations • Self-descriptive messages • Hypermedia as the engine of the application state
26. Feedback Design Delivery Prototype Development SIMPLE API LIFECYCLE
27. REFERENCE • http://apiary.io • http://apiblueprint.org • https://github.com/apiaryio/mson • http://www.ics.uci.edu/~fielding/pubs/dissertation/ rest_arch_style.htm