The document discusses notes from the 2014 API Craft conference. Several topics are mentioned, including hypermedia, affordances, building hypermedia servers, documenting APIs, and the future of mobile APIs. Hypermedia is presented as a way to avoid hardcoding clients, reduce versioning problems, and make resource relations and states discoverable. Challenges with hypermedia include unclear definitions, payload size, and potential bad user experiences on mobile. The document also provides suggestions for how to work with APIs still in development and resources related to topics from the conference.

1. API Craft Notes
2014
Anallely Olivares

3. An Open Space Conference...

4. An Open Space Conference...

5. A lot of topics

6. And more...

7. HYPERMEDIA HYPERMEDIA
HYPERMEDIA HYPERMEDIA HYPERMEDIA
HYPERMEDIA HYPERMEDIA HYPERMEDIA
HYPERMEDIA
HYPERMEDIA
HYPERMEDIA
A lot of interest for...

8. MEDIA -----> Problem Domain
HYPERMEDIA ----> Solution
The more descriptive the media type, the easier it is to talk about the
problem (and solution)
Hypermedia...

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

10. Affordances:
Hypermedia...

11. Affordances:
{
"balance": 100,
"_links": {
"http://mysite.com/rels/deposit": {"href": "/account/deposit"},
"http://mysite.com/rels/withdraw": {"href": "/account/withdraw"},
},
}
Hypermedia...

12. Affordances:
{
"balance": 100
}
or
{
"balance": 100,
"_links": {
"http://mysite.com/rels/deposit": {"href": "/account/deposit"},
},
}
Hypermedia...

13. Hypermedia

14. Hypermedia

15. Hypermedia

16. Hypermedia
Client-server dance
Coupling is the enemy

17. * Unbreakable APIs
- Self repairing APIs
- (Adamantium)
Hypermedia

18. ● 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

19. ● 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

20. ● 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

21. ● 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

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

23. 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

24. 3. Alias in a way that may sense to the client.
Referential data
{
...
match_event: 12
}
rather than
{
...
match_event: goal
}

25. 4. Customized responses
Referential data

26. Referential data

27. Techniques for building hypermedia servers
1. Blocking resources doesn't scale
- Compensation actions
Inventory example

28. Techniques for building hypermedia servers
2. Dealing with async
- Bus architecture
- An url where consult the progress state

29. 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

30. - 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

31. - Prepared to change
API First Date

32. 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

33. - WADL
- Swagger
- API Blueprint
- RAML
- IO Docs
- RepreZen DSL
Implementation detail
Interoperability
API description languages. Interoperability
* Top down / Contract first
* Bottom up / Code first

34. ● 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

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

36. * 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 Amundsen
http://www.slideshare.net/rnewton/not-rocketscience-22155935
* Hypermedia as the engine of application state, the client-server dance
http://www.bizcoder.com/hypermedia-as-the-engine-of-application-state-the-client-server-dance
Resources