I Love APIs

Coverage:
https://www.forbes.com/sites/danwoods/2015/10/19/dont-get-ubered-apis-hold-key-to-digital-transformation/?sh=50112fea182c#:~:text=One%20recommendation%20that,deep%20experience.

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

How:
Fake the backend. Then when the UI code is completely done, make the backend real.

Transcript

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

   View Slide

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.
   

   View Slide

3. Mike McNeil
   @mikermcneil
   github.com/mikermcneil
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

8. REST
   No
   for the weary.
   1.
   

   View Slide

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

   View Slide

10. REST CRUD
    ===
    For our purposes:
    

    View Slide

11. Create
    Read
    Update
    Delete
    

    View Slide

12. first version (late 2011)
    

    View Slide

13. View Slide

14. custom app-specific adapters

    (LDAP / Active Directory / etc)
    ~20 other community adapters
    

    View Slide

15. View Slide

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

    View Slide

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

    View Slide

18. Search the store.
    

    View Slide

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

    View Slide

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
    

    View Slide

21. Log in.
    

    View Slide

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

    View Slide

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

    View Slide

24. So do we use CRUD?
    

    View Slide

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

    View Slide

26. 2. Upside Down
    

    View Slide

27. API first?
    

    View Slide

28. API first?
    API centric, UI first.
    

    View Slide

29. We need to flip things
    upside down
    

    View Slide

30. omated tests for code
    write documentation for
    write 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
    

    View Slide

31. omated tests for code
    write documentation for
    write 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
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

41. 3. Everyday APIs
    

    View Slide

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

    View Slide

43. Human
    Client Devices
    Cloud
    

    View Slide

44. Human
    Client Devices
    Cloud
    

    View Slide

45. Human
    Client Devices
    Cloud
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

49. )
    }
    (
    function {
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

55. a
    b
    c
    exits
    inputs
    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)
    *
    *
    *
    

    View Slide

56. The
    Node Machine
    Project
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

60. npm install
    

    View Slide

61. npm publish
    

    View Slide

62. Machinepacks
    node-machine.org/spec
    

    View Slide

63. View Slide

64. View Slide

65. View Slide

66. node-machine.org
    sailsjs.org
    

    View Slide

67. Questions?
    @mikermcneil
    node-machine.org
    

    View Slide

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)
    

    View Slide