api craft notes

API Craft Notes 2014

Anallely Olivares

An Open Space Conference...

An Open Space Conference...

A lot of topics

And more...

HYPERMEDIA HYPERMEDIAHYPERMEDIA HYPERMEDIA HYPERMEDIA

HYPERMEDIA HYPERMEDIA HYPERMEDIA

HYPERMEDIA HYPERMEDIA HYPERMEDIA

A lot of interest for...

MEDIA -----> Problem Domain

HYPERMEDIA ----> Solution

The more descriptive the media type, the easier it is to talk about the problem (and solution)

Hypermedia...

* A client able to determine valid possibilities from links and forms in the message itself as a guide

Semantics

Hypermedia...

Affordances:

Hypermedia...

Affordances:

{

"balance": 100,

"_links": {

"http://mysite.com/rels/deposit": {"href": "/account/deposit"},

"http://mysite.com/rels/withdraw": {"href": "/account/withdraw"},

},

}

Hypermedia...

Affordances: {

"balance": 100

}

or{

"balance": 100,

"_links": {

"http://mysite.com/rels/deposit": {"href": "/account/deposit"},

},

}

Hypermedia...

Hypermedia

Hypermedia

Hypermedia

Hypermedia

Client-server dance

Coupling is the enemy

* Unbreakable APIs - Self repairing APIs - (Adamantium)

Hypermedia

● Hypermedia: Why Y'all Hatin'?

PROS○ Avoids hardcoding and potentially breaking clients○ Reduces versioning problems○ Avoids logic being duplicated on server and clients○ Gives meaning to resource relations○ Affordance discoverability, some states are not available from current

state -> Adaptable clients

How do we get people who don't give a shit about hypermedia to adopt it

● Hypermedia: Why Y'all Hatin'?

PROS…

● Reduces developer annoyance.● Improves understanding between servers and client● One of its goals is not needing human factor to fix something broken

(Or at least reduce human participation)

How do we get people who don't give a shit about hypermedia to adopt it

● Hypermedia: Why Y'all Hatin'?

CONS - The definition of hypermedia is not completely clear - Payload size - More work - Hypermedia is not unbreakable (POST, PUT) - Linking is useful, what about the rest? - Mobile apps - round trips can cause bad UX

How do we get people who don't give a shit about hypermedia to adopt it

● Hypermedia: Why Y'all Hatin'?

RESPONSES

- Design should avoid traversal, things are one step away (UX Clicks) - Tooling needed - A human-machine representation balance is needed (JSON) - Simple patterns (best practices) must arise (example: adding a new field) - People don't read docs. Media types help provide the information.

How do we get people who don't give a shit about hypermedia to adopt it

● Metaphor

How do we get people who don't give a shit about hypermedia to adopt it

Consider resources: * Posts * Comments

1. Separated resources? or together? (It depends)

2. Doesn't expose the underlying storage means or relations of the data. Persistent data != Expose data No foreign keys

Referential data

3. Alias in a way that may sense to the client.

Referential data

{ ... match_event: 12 }

rather than

{ ... match_event: goal }

4. Customized responses

Referential data

Referential data

Techniques for building hypermedia servers

1. Blocking resources doesn't scale - Compensation actions

Inventory example

Techniques for building hypermedia servers

2. Dealing with async

- Bus architecture - An url where consult the progress state

How do you write client apps for apis that are still in development?

* Coordinated effort between api client (requirements) and api server* Design - UX Analogy

API First Date

- Communication- Weekly sprints- Feedback

- Data contracts - Mock data

- One source of truth. Let's build a [swagger, apiary, raml] doc then build an api to look like that, and a client to consume resources like that.

API First Date

- Prepared to change

API First Date

API First Date - Keep it real, remember the goal- API is a tool - The goal is always something else that isn't an API or a Client - Frustration tolerant - Open enough

- WADL- Swagger- API Blueprint- RAML- IO Docs- RepreZen DSL

Implementation detailInteroperability

API description languages. Interoperability

* Top down / Contract first

* Bottom up / Code first

● Audience (aimed to developers? product owners?, etc.)● Versioning● Quick Start Guide● Authentication/Handshake● Code Examples (Curl, etc)● Limits (Throttling/etc.)● Error Handling● API Status page (Up/down)● Feedback (Form/analytics)● Licensing

Documentation - Items

& Future of mobile APIs and protocols (What is after HTTP?)

● Optimized responses

● Think about the possibilities establishing relation between entities

● Other protocols arise, based on broadcasting

● Interoperability: every node exposes an API. Then every node has server/client capabilities

● Pub / Sub

● Communication becomes alive. Discoverability.

● Devices able to learn and adapt

● Not depending only on one API, but with a lot of available APIs

What will mobile APIs look like 10 years next?

* What Is An OpenSpace Conference? http://www.mindviewinc.com/Conferences/OpenSpaces

* Proceedings for API Craft Conference v2

https://github.com/apicraft/detroit2014/wiki

* Implementing Hypermedia Clients: It's Not Rocket Science – Mike Amundsenhttp://www.slideshare.net/rnewton/not-rocketscience-22155935

* Hypermedia as the engine of application state, the client-server dancehttp://www.bizcoder.com/hypermedia-as-the-engine-of-application-state-the-client-server-dance

Resources