36
API Craft Notes 2014 Anallely Olivares

Api craft notes

Embed Size (px)

DESCRIPTION

A little brief about the conference of API Craft Conference 2014

Citation preview

Page 1: Api craft notes

API Craft Notes 2014

Anallely Olivares

Page 2: Api craft notes
Page 3: Api craft notes

An Open Space Conference...

Page 4: Api craft notes

An Open Space Conference...

Page 5: Api craft notes

A lot of topics

Page 6: Api craft notes

And more...

Page 7: Api craft notes

HYPERMEDIA HYPERMEDIAHYPERMEDIA HYPERMEDIA HYPERMEDIA

HYPERMEDIA HYPERMEDIA HYPERMEDIA

HYPERMEDIA HYPERMEDIA HYPERMEDIA

A lot of interest for...

Page 8: Api craft notes

MEDIA -----> Problem Domain

HYPERMEDIA ----> Solution

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

Hypermedia...

Page 9: Api craft notes

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

Semantics

Hypermedia...

Page 10: Api craft notes

Affordances:

Hypermedia...

Page 11: Api craft notes

Affordances:

{

"balance": 100,

"_links": {

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

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

},

}

Hypermedia...

Page 12: Api craft notes

Affordances: {

"balance": 100

}

or{

"balance": 100,

"_links": {

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

},

}

Hypermedia...

Page 13: Api craft notes

Hypermedia

Page 14: Api craft notes

Hypermedia

Page 15: Api craft notes

Hypermedia

Page 16: Api craft notes

Hypermedia

Client-server dance

Coupling is the enemy

Page 17: Api craft notes

* Unbreakable APIs - Self repairing APIs - (Adamantium)

Hypermedia

Page 18: Api craft notes

● 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

Page 19: Api craft notes

● 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

Page 20: Api craft notes

● 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

Page 21: Api craft notes

● 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

Page 22: Api craft notes

● Metaphor

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

Page 23: Api craft notes

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

Page 24: Api craft notes

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

Referential data

{ ... match_event: 12 }

rather than

{ ... match_event: goal }

Page 25: Api craft notes

4. Customized responses

Referential data

Page 26: Api craft notes

Referential data

Page 27: Api craft notes

Techniques for building hypermedia servers

1. Blocking resources doesn't scale - Compensation actions

Inventory example

Page 28: Api craft notes

Techniques for building hypermedia servers

2. Dealing with async

- Bus architecture - An url where consult the progress state

Page 29: Api craft notes

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

Page 30: Api craft notes

- 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

Page 31: Api craft notes

- Prepared to change

API First Date

Page 32: Api craft notes

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

Page 33: Api craft notes

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

Implementation detailInteroperability

API description languages. Interoperability

* Top down / Contract first

* Bottom up / Code first

Page 34: Api craft notes

● 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

Page 35: Api craft notes

& 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?

Page 36: Api craft notes

* 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