The document discusses the need for more reusable APIs and outlines 10 things API developers should stop doing, including mapping semantics to protocols instead of messages, hiding update and query rules in documentation, and requiring clients to recode and redeploy at random. It argues that APIs should map semantics to messages, use inline hypermedia controls, provide SDKs when needed, share message models rather than object models, describe services abstractly, put workflow in messages, avoid breaking changes, and distribute storage and execution rather than relying on single points of failure. The document concludes that making these changes to follow best practices for reusable APIs is not complicated, though some aspects may be hard.

1. Reusable APIs
Mike Amundsen
@mamund
@Layer7 @CAInc

2. We need more reusable APIs
Too many "snowflake" APIs
Too few generic descriptions of APIs
Too often we code from "zero" every time

3. We can do better

4. Top 10 things we should
STOP
doing

5. Stop mapping semantics to protocols

6. Map semantics to messages instead.

7. Stop hiding update & query rules in
human-readable documentation

8. Use inline hypermedia controls instead.

9. Stop requiring devs to be protocol gurus

10. Provide "accommodations" like SDKs
when appropriate

11. Stop making everyone use the
same object model

12. Share message models,
not object models

13. Stop describing services as
single instances

14. Describe services as abstract classes.

15. Stop baking workflow into client code

16. Put workflow in the message
via hypermedia

17. Stop breaking others people's code

18. Take the "no breaking changes" pledge

19. Take the "no breaking changes" pledge

20. Stop making client devs re-code & redeploy at random

21. Use "dark release" to allow client devs
to update on their own schedule

22. Stop adding single points of failure

23. Distribute not just storage,
but also execution.

24. Stop pretending the Web defies the laws
of probability and physics

25. We can do better
10. Map semantics to messages
5. Put workflow in messages
9. Use inline hypermedia
4. Take the "no breaking
changes" pledge
8. Provide SDKs when
appropriate
7. Share messages, not objects
6. Describe services as
abstract classes
3. Use "dark release"
2. Distribute storage and
execution
1. Obey the laws of
probability and physics

26. None of this is complicated
Some of it is hard.

27. Let's talk about
Reusable APIs
Mike Amundsen
@mamund
@Layer7 @CAInc
g.mamund.com/top10stop