Fosscomm #8: A hypermedia API design lifecycle

API ATHENS MEETUP APIs | People Tech | Connect http://www.meetup.com/API-Athens

• Jun 2, 2014 • 500 API Artisans • 9
Past Meetups • 1 Upcoming Meetup http://www.meetup.com/API-Athens

http://www.meetup.com/API-Athens NEXT: “APIs, IoT and a bit of business” November
11, 2015 7:00 PM The CUBE Athens

A hypermedia API design lifecycle Dimitrios Tydeas Mengidis [email protected] @dmtrsslvdr

Hypermedia API Design lifecycle

Web API means HTTP

HTTP is RFC7230

MUST MUST NOT SHOULD SHOULD NOT MAY

Client ⇄ Server

Client An HTTP "client" is a program that establishes a
connection to a server for the purpose of sending one or more HTTP requests.

Server An HTTP "server" is a program that accepts connections
in order to service HTTP requests by sending HTTP responses.

Client Request

METHOD Request-Header: value ... “Payload Body” uri

METHOD Request-Header: value ... “Payload Body” 1 uri

HTTP Methods GET, POST, PUT, DELETE HEAD, CONNECT, TRACE,OPTIONS

METHOD Request-Header: value ... “Payload Body” 1 uri

GET Request-Header: value ... “Payload Body” 1 uri

GET Request-Header: value ... “Payload Body” 2 uri

Unique Resource Identifier ...a compact sequence of characters that identifies
an abstract or physical resource. RFC3986

GET Request-Header: value ... “Payload Body” 2 /events

GET Request-Header: value ... “Payload Body” 3 /events

GET Accept: text/html ... “Payload Body” 3 /events

GET Accept: text/html ... “Payload Body” 4 /events

A payload within a GET request message has no defined
semantics; sending a payload body on a GET request might cause some existing implementations to reject the request. 4

GET Accept: text/html ... /events

Server Response

Status code Response-Header: value ... “Payload Body”

Status code Response-Header: value ... “Payload Body” 1

Status codes 2xx 3xx 4xx 5xx

200 Response-Header: value ... “Payload Body” 1

200 Response-Header: value ... “Payload Body” 2

200 Content-Type: application/json ... “Payload Body” 2

200 Content-Type: application/json ... “Payload Body” 3

200 Content-Type: application/json ... { “data”: [ “...” ] }
3

{ “data”: [ “...” ] }

[Hyper]Media Types

Hypermedia A way for the server to tell the client
what request what HTTP requests the client want to make in the future

text/html

GET http://teiath.gr Accept: text/html

GET http://teiath.gr Accept: text/html 200 Content-Type: text/html <html><head>...

{ “data”: [ “...” ] }

{ json:api } application/vnd.api+json

{ "data": [ { "id": "1", "type": "talks", "links": {
"self": "http://we.edu/talks/1", "author": { "related": "http://we.edu/talks/1/author" } } } ] }

Design lifecycle

Sketch ⇄ Prototype ⇢ Implement

Sketch ⇄ Prototype

Sketch

Prototype

Apiblueprint API Blueprint is a documentation-oriented API description language for
humans. http://github.com/apiaryio/api-blueprint/

# We edu We ed is an API allowing consumers
to ... # We edu API Root [ / ] ## Retrieve the Entry Point [GET] + Response 200 (application/json) { "data": [ { "id": "1", "type": "talks", //… }] }

Drakov Mock server that implements the API Blueprint specification

Dreed CLI tool for validating API documentation written in API
Blueprint

Resources Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing {json:api}:
A standard for building APIs in JSON API Design Lifecycle / Honza Javorek New Acropolis Museum / Bernard Tschumi Architects apiblueprint: API Documentation with powerful tooling Failing Fast with API Design / Ronnie Mitra Contact Dimitrios Tydeas Mengidis, Avocarrot.com tydeas.dr@gmail. com @dmtrsslvdr

Fosscomm #8: A hypermedia API design lifecycle

Fosscomm #8: A hypermedia API design lifecycle

More Decks by Dimitrios Flaco Mengidis

Other Decks in Programming

Featured

Transcript