The document discusses APIs and API-first development. It argues that traditional development processes focus too much on data models and server code before APIs and user interfaces. An API-centric process prioritizes designing APIs and user interfaces first before implementing backend functionality. Well-designed APIs can be implemented later as the "real" backend code, after prototypes are built with "fake" backend code. Everyday APIs like functions and modules define interfaces that are used without being explicitly designed. The document promotes standardizing the documentation of JavaScript functions as APIs.

1. I <3 APIs
San Jose, October 2015
API first?
@mikermcneil

2. API first?
©2015 Apigee Corp. All Rights Rese
The views expressed in this presentation are those
of the presenter, and not necessarily those of Apigee
Corporation or the presenter’s employer.

3. Mike McNeil
@mikermcneil
github.com/mikermcneil

4. Mike McNeil
Founder/CEO Treeline (YC W15)
creator & BDFL of

5. the leading open-source
MVC framework for Node.js

6. demo
For a deeper dive, google:
“Sails.js Platzi”

7. 1. No REST For The Weary
2. Upside Down
3. Everyday APIs

8. REST
No
for the weary.
1.

9. A good starting point
for building any cloud API.
REST

10. REST CRUD===
For our purposes:

11. Create
Read
Update
Delete

12. first version (late 2011)

14. custom app-specific adapters
(LDAP / Active Directory / etc)
~20 other community adapters

16. A noun-centric ontology
works great for building
databases.

17. Never works for 100%
of any app.
CRUD

18. Search the store.

19. search({
query:
‘shoes’
});
Search the store.

20. Product.find({
or:
[
{
name:
{contains:
’shoes’}},
{
description:
{contains:
’shoes’}}
]
});
//
…also
search
recipes
//
…also
search
comments
then
for
each
one,
look
up
//
the
containing
product
or
recipe…
Search the store.
//
…then
rank
results..
oh
wait
but
actually
this
should
all
be
in
an
index
of
some
kind

21. Log in.

22. login({
username:
‘mikermcneil’
password:
‘c4tP4rTy’
});
Log in.

23. Session.create({
userId:
User.find({
username:’mikermcneil’
password:
‘c4tP4rTy
}).id
})
Log in.

24. So do we use CRUD?

25. Because half the time,
we don’t actually know what
we’re supposed to be building.

26. 2. Upside Down

27. API first?

28. API first?
API centric, UI first.

29. We need to flip things
upside down

30. omated tests for code
write documentation forwrite code
manually test code deploy co
discover bug
remember how code wo
fix code
manually test code
discover that automated tests fail now
update automated tests
ation redeploy co
design

31. omated tests for code
write documentation forwrite code
manually test code deploy co
discover bug
remember how code wo
fix code
manually test code
discover that automated tests fail now
update automated tests
ation redeploy co
design

32. How we think as product
designers:
1. User interface design
2. Interaction design
3. Cross fingers (development starts)
…
4. Oh crap, one more thing I forgot to mention…
5. Can I see a preview?
6. AHHH WHAT IS THIS?!

33. “Traditional”
Development Process
1.Design data model
2.Implement custom server code
3.Start implementing custom UI code
c. 2005

34. “Traditional”
Development Process
1.Design data model
2.Implement custom server code
3.Start implementing custom UI code
4.AHHHHHHH WTF IS THIS??!
5.Change the data model, change server code, change UI
code, change API docs (but you probably don’t have any)
c. 2005

35. “NoSQL”
Development Process
1.Implement custom server code
2.Implement custom UI code
3.Stumble upon (then maybe even document!)
your cloud API
4.Stumble upon your data model
c. 2011

36. “NoSQL”
Development Process
1.Implement custom server code
2.Implement custom UI code
3.AHHHHHHH WTF IS THIS??!
4.Change server code, change UI code
5.Stumble upon & document your cloud API
6.Stumble upon your data model
c. 2011

37. “API-Centric”
Development Process
1.Implement custom code for each UI
2.Implement fake server code
3.Stumble upon your cloud API
4.Implement real server code
5.Stumble upon your data model

38. “API-Centric”
Development Process
1.Implement custom code for each UI
2.Implement fake server code
3.AHHHHHHH WTF IS THIS??! (one or more of the UIs changed)
4.Change UI code
5.Stumble upon your cloud API
6.Now implement real server code
7.Stumble upon your data model

39. Goal:
Minimize technical debt, code changes,
and rewrites.
How:
Show stakeholders and customers the
developing or fully-implemented UI as
early as possible.

40. It’s ok if the backend
starts off… fake.

41. 3. Everyday APIs

42. We don’t design most of
the APIs we use.

43. Human
Client Devices
Cloud

44. Human
Client Devices
Cloud

45. Human
Client Devices
Cloud

46. Human
Client Devices
Cloud
custom UI code
custom server code

47. Every time we write a function,
we’re designing an API.

48. We're just giving you functions
that return functions that you
do things with.
Doug Wilson
Lead Maintainer, Express

49. )
}
(function {

50. )
}
(function {a b c, ,

51. )
}
(function {a b c, ,
console.log(“hi”);

52. )
}
(function {a b c, ,
console.log(“hi”);
return a b c ;+ +

53. )
}
(function {a b c, ,
console.log(“hi”);
return a b c ;+ +
if (Math.random()>0.5) {
}
throw new Error();

54. )
}
(function {
console.log(
a
b
c
return a b c ;+ +
exits
inputs
throw new Error();
if (Math.random()>0.5) {
}
behavior

55. a
b
c
exitsinputs
Output: number
Output: Error
error
success
Description: Sorry, you got unlucky.
First number
Second number
Third number
(e.g. 7)
(e.g. 2)
(e.g. 3)
(e.g. 1)
DESCRIPTION:
Add the 3 provided numbers together.
MORE INFO URL:
http://example.com/docs/math/add
FRIENDLY NAME:
Add numbers
PACKAGE:
machinepack-math (v3.2.9)
*
*
*

56. The
Node Machine
Project

57. Like Swagger
for
node-machine.org/spec
JavaScript functions.

58. Like Swagger
for
node-machine.org/spec
middleware.

59. Like Swagger
for
node-machine.org/spec
Node modules.

60. npm install

61. npm publish

62. Machinepacks
node-machine.org/spec

66. node-machine.org
sailsjs.org

67. Questions?
@mikermcneilnode-machine.org

68. The Machine Specification
Branching and convergence
Lamda functions as arguments
Type validation and coercion (recursive)
Automatically generated documentation
machine-­‐as-­‐script
machine-­‐as-­‐action
(what’s new)