Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Design with Apiary

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
March 17, 2016

API Design with Apiary

As presentent on ofmForum.

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

March 17, 2016
Tweet

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