API Design with Apiary

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" }
8. None
9. None

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

22. None

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