API Design with Apiary - Speaker Deck

Slide 1

Slide 1 text

API DESIGN WITH APIARY Z – @zdne Apiary.io

Slide 2

Slide 2 text

4 STAGES OF API MATURITY API as a by- product of building apps API documentation generated from code Design-ﬁrst API Development API Design Consistency

Slide 3

Slide 3 text

APIARY.IO

Slide 4

Slide 4 text

DESIGN-FIRST

Slide 5

Slide 5 text

API DESCRIPTION • API Blueprint • OpenAPI Speciﬁcation (Swagger) • Others (RAML, WADL, WSDL, Email, Word document)

Slide 6

Slide 6 text

API BLUEPRINT

Slide 7

Slide 7 text

# User [/user] ## Retrieve [GET] Retrieves the . + Response 200 (application/json) { "name": "John" }

Slide 8

Slide 8 text

No content

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

API LIFECYCLE

Slide 11

Slide 11 text

Preparation Design Development Delivery Consumption Analysis CLASSIC API LIFECYCLE

Slide 12

Slide 12 text

Preparation Design & Prototype Development Delivery Consumption Analysis API LIFECYCLE WITH APIARY

Slide 13

Slide 13 text

Preparation 1. Deﬁne domain semantics 2. Choose architectural style 3. Deﬁne a style guide*

Slide 14

Slide 14 text

Design & Prototype 1. Formalize API in an API Description format* 2. Put API Description in a VCS 3. Circulate & Review 4. Apiary Mock Server

Slide 15

Slide 15 text

Develop 1. API Description in the same repository as implementation 2. Test locally 3. Test with Apiary 4. Test in CI

Slide 16

Slide 16 text

Deliver 1. Share VCS repository 2. Share Apiary Documentation 3. Embed Apiary Documentation

Slide 17

Slide 17 text

Consume 1. Apiary Documentation 2. Apiary Mock Server 3. Documentation Console 4. Language Examples 5. Apiary Trafﬁc Inspector 6. Apiary Proxy

Slide 18

Slide 18 text

Analysis

Slide 19

Slide 19 text

BONUS: GOVERNANCE • Design Rules • Style Guides • Better DX through CONSISTENCY

Slide 20

Slide 20 text

BONUS: MSON • Human readable data description • Reusable, format-agnostic data modeling language • Data is your API

Slide 21

Slide 21 text

TRY IT NOW http://apiary.io Q&A @apiaryio

Slide 22

Slide 22 text

No content

Slide 23

Slide 23 text

MIND SHIFT • Describe resource NOT representation • Deﬁne domain semantics • Reuse common semantics • Do NOT focus on technical details • URIs • representations • schema validations

Slide 24

Slide 24 text

API ISN’T… • API is not pretty URLs • API is not HTTP Verbs • API is not CRUD • API is not JSON

Slide 25

Slide 25 text

REST ARCHITECTURAL STYLE • Client–server • Stateless • Cacheable • Layered system • Code on Demand (optional) • Uniform Interface • Identiﬁcation of resources • Manipulation through representations • Self-descriptive messages • Hypermedia as the engine of the application state

Slide 26

Slide 26 text

Feedback Design Delivery Prototype Development SIMPLE API LIFECYCLE

Slide 27

Slide 27 text

REFERENCE • http://apiary.io • http://apiblueprint.org • https://github.com/apiaryio/mson • http://www.ics.uci.edu/~ﬁelding/pubs/dissertation/ rest_arch_style.htm