I Love APIs - Oct 2015

I <3 APIsSan Jose, October 2015

API first?

@mikermcneil

API first?

©2015 Apigee Corp. All Rights Reserved.

The views expressed in this presentation are those of the presenter, and not necessarily those of Apigee Corporation or the presenter’s employer.

1

Mike McNeil

@mikermcneilgithub.com/mikermcneil

Mike McNeil

Founder/CEO Treeline (YC W15)

creator & BDFL of

the leading open-source MVC framework for Node.js

demo

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

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

RESTNo

for the weary.

1.

A good starting point for building any cloud API.

REST

REST CRUD===

For our purposes:

Create Read Update Delete

first version (late 2011)

custom app-specific adapters(LDAP / Active Directory / etc)

~20 other community adapters

A noun-centric ontology works great for building

databases.

Never works for 100% of any app.

CRUD

Search the store.

search({      query:  ‘shoes’  });

Search the store.

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

Log in.

login({      username:  ‘mikermcneil’      password:  ‘c4tP4rTy’  });

Log in.

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

Log in.

So do we use CRUD?

Because half the time, we don’t actually know what

we’re supposed to be building.

2. Upside Down

API first?

API first? API centric, UI first.

We need to flip things upside down

write automated tests for code

write documentation for codewrite code

manually test code deploy code to server

discover bug

remember how code works

fix code

manually test code

discover that automated tests fail now

update automated tests

update documentation redeploy code to server

design

write automated tests for code

write documentation for codewrite code

manually test code deploy code to server

discover bug

remember how code works

fix code

manually test code

discover that automated tests fail now

update automated tests

update documentation redeploy code to server

design

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

“Traditional” Development Process

1.Design data model 2.Implement custom server code 3.Start implementing custom UI code

c. 2005

“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

“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

“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

“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

“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

Goal: Minimize technical debt, code changes, and rewrites.

How: Show stakeholders and customers the developing or fully-implemented UI as early as possible.

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

3. Everyday APIs

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

Human

Client Devices

Cloud

Human

Client Devices

Cloud

Human

Client Devices

Cloud

Human

Client Devices

Cloud

custom UI code

custom server code

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

We're just giving you functions that return functions that you do things with.

Doug WilsonLead Maintainer, Express

)

}

(function {

)

}

(function {a b c, ,

)

}

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

)

}

(function {a b c, ,

console.log(“hi”);

return a b c;+ +

)

}

(function {a b c, ,

console.log(“hi”);

return a b c;+ +

if (Math.random()>0.5) {

} throw new Error();

)

}

(function {

console.log(

a

b

c

return a b c;+ +

exits

inputs

throw new Error();

if (Math.random()>0.5) {

}

behavior

console.log(

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)

*

*

*

The Node Machine Project

Like Swaggerfor

node-machine.org/spec

JavaScript functions.

Like Swaggerfor

node-machine.org/spec

middleware.

Like Swaggerfor

node-machine.org/spec

Node modules.

npm install

npm publish

Machinepacks

node-machine.org/spec

node-machine.org

sailsjs.org

Questions?

@mikermcneilnode-machine.org

The Machine Specification

Branching and convergence

Lamda functions as arguments

Type validation and coercion (recursive)

Automatically generated documentation

machine-­‐as-­‐scriptmachine-­‐as-­‐action

(what’s new)