Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Be The API - VMware UserCon 2016

163 views

Published on

A brief introduction to the concept of application program interfaces, how they differ from the CLI and how that theory applies to our day jobs. Communication is hard. In an exploration of what software engineering can teach us about our daily lives, let's explore the interfaces we have between each other. We might just find the metaphor that makes communication a little easier. Takeaway: determine what your API is – what inputs you take from others and what they can expect in return.

Published in: Engineering
  • Be the first to comment

  • Be the first to like this

Be The API - VMware UserCon 2016

  1. 1. Be The API an exploration of careers, supported by code and memes by @mjbrender
  2. 2. Business Logic
  3. 3. The Happy Place
  4. 4. The Happy Place
  5. 5. My Less Happy Place
  6. 6. No, Not Again
  7. 7. “Hey, Sisyphus, when you’ve got a minute I’d like to discuss this progress report with you.”
  8. 8. > cd $HOME > > > bash ./admin_script fixing foo
  9. 9. > vim ./admin_script cmd | xarg –n 1 sed –i “s/server/foo/g” | grep -i up >err.log 2>&1
  10. 10. “An Application Programming Interface is a set of routines, protocols, and tools for building software applications.”
  11. 11. History of APIs 2000
  12. 12. Structured input and output
  13. 13. vSphere API source
  14. 14. Many Other APIs JSON JSON
  15. 15. is the API the new CLI ?
  16. 16. > cmd | grep | sed | awk
  17. 17. the API the new CLI (if and only if you use the CLI like this example)
  18. 18. > cmd | grep | sed | awk
  19. 19. JSON JSON
  20. 20. JSON JSON
  21. 21. API is a machine interface CLI is a user interface GUI is a user interface
  22. 22. An API says: Request this. Get that.
  23. 23. {you}
  24. 24. {myapi}
  25. 25. serverAPI myctl {myapi} service
  26. 26. GET job/ Return a description of my job. There are no options available for this endpoint.
  27. 27. > myctl job list Matt is a Developer Advocate. Developer Advocates are technical community contributors key to accelerating project adoption through internal coordination & targeted external contribution.
  28. 28. GET contact/ Returns a list of available forms of contact. type required Return whether the contact is personal or professional Values: personal, professional, all include_preference optional Boolean preference as defined by the service Example Value: true include_reply_time optional Return average response time for request Example Value: false Response formats JSON Requires authentication? No Rate limited? Yes
  29. 29. curl http://localhost/v1/contact ?type=all { ”contact": { ”email": [ { “type": “professional", “to": “REDACTED", }, { “type": “personal", “to": “REDACTED", }, ], ”tweet": [ { "type": “personal”, “to": “@mjbrender", } ], ”call": [ { "type": “personal”, “to": “+REDACTED", } ] } }
  30. 30. > myctl contact list --all TYPE PREFERENCE REPLY TIME email 2 3d text 3 1m tweet 1 30s call 4 5d
  31. 31. PUT contact/[:to] Request that gets in contact with the API owner. Returns string response to the request. from required Return location appropriate for the endpoint Example Value: @mjbrender, mjbrender@gmail.com message required Reason for the contact Example Value: “Thought you’d like this post” urgency optional Definition of how quickly a reply is required. Values: Low, Medium, High include_lead_time optional Boolean to include approximate time to respond. Example Value: true
  32. 32. curl -H “Content-Type: application/json” -X POST –d ‘{ “from”: “@vBrianGraf”, “description”: “Hey!” } http://localhost/v1/contact/@ mjbrender { ”confirmation": “Thanks for getting in touch. I’ll response back as soon as time allows.” }
  33. 33. { ”confirmation": “Thanks for getting in touch. Since this involves something urgent, I’ll get back to you as soon as I can.” } curl -H “Content-Type: application/json” -X POST –d ‘{ “from”: “josie@google.com”, “description”: “House on Fire”, “urgency”: “high” } http://localhost/v1/contact/ mjbrender@gmail.com
  34. 34. GET job/skill Returns a list of advertised job skills. type optional Return the category of work this falls under Values: ENG, MKT, SALES, FINANCE, MGMT include_preference optional Boolean preference as defined by the service provider. Defined on a scale from 1-7 with 7 as most preferred Example Value: 3 include_level optional Boolean level of expertise of the service provider. Expertise is defined on a scale from 1-7 with 7 as best Example Value: 7 Response formats JSON Requires authentication? No Rate limited? No
  35. 35. > myctl skill list --type=ENG -p SKILL TYPE PREFERENCE Build Automation ENG 5 Product Mgmt ENG 5 Dev Mgmt ENG 4 Traditional IT ENG 3 Cloud Native ENG 7 Ruby Developer ENG 3 Go Developer ENG 3
  36. 36. > myctl skill list --type=ENG -p SKILL TYPE PREFERENCE Build Automation ENG 5 Product Mgmt ENG 5 Dev Mgmt ENG 4 Traditional IT ENG 3 Cloud Native ENG 7 Ruby Developer ENG 3 Go Developer ENG 3
  37. 37. > myctl skill list --type=ENG -l SKILL TYPE SKILL LEVEL Build Automation ENG 2 Product Mgmt ENG 5 Dev Mgmt ENG 4 Traditional IT ENG 5 Cloud Native ENG 3 Ruby Developer ENG 2 Go Developer ENG 2
  38. 38. > myctl skill list --type=ENG -l SKILL TYPE SKILL LEVEL Build Automation ENG 2 Product Mgmt ENG 5 Dev Mgmt ENG 4 Traditional IT ENG 5 Cloud Native ENG 3 Ruby Developer ENG 2 Go Developer ENG 2
  39. 39. > myctl skill list --type=MKT -l SKILL TYPE SKILL LEVEL PowerPointing MKT 6 Podcasting MKT 6 Blogging MKT 4 Public Speaking MKT 4 Product Messaging MKT 5 Logo Design MKT 5 Social Media MKT 5
  40. 40. GET job/request/ Review active work requests with expected completion dates. type optional Return the category of work this falls under Values: ENG, MKT, SALES, FINANCE, MGMT include_preference optional Boolean preference as defined by the service provider Example Value: true include_lead_time optional Boolean to include default lead time per request Example Value: true Response formats JSON Requires authentication? No Rate limited? No
  41. 41. > myctl work list -t -lt REQUEST TYPE LEAD TIME Create PPT MKT 7d Define OSS Release ENG 5d Test Automation ENG 3d Write Blog Post MKT 2d Re to Sales MGMT .5d Schedule Meeting MGMT .25d Create other PPT MKT 7d
  42. 42. PUT job/request/ Request that gets in contact with the API owner. Returns expected response time. title required Boolean preference as defined by the service Example Value: true description required Return average response time for request Example Value: false urgency required Return average response time for request Example Value: false authorized optional Return average response time for request Example Value: true
  43. 43. Valid Responses • “Here you go.” • “I can’t do that.” • “I’m on it. I’m estimating a delivery time of” + GET job/requests/[:type]?lead_time • “I can’t help you with this right now, I’m at capacity. Please contact my manager.” • “I can’t help you right now due to other urgent priorities. Please contact my manager.” • “I will get on it right away. Here is the other work that will be delayed by at least 2 business days by this request:” + GET job/requests/
  44. 44. GET contact/ job/ job/skill/ job/request/ PUT contact/ job/request/ {myapi}
  45. 45. What’s undocumented? Endpoint GET hobby/ Options tone := Reflect.type(tone)
  46. 46. An API says: Request this. Get that.
  47. 47. API is a machine interface CLI is a user interface GUI is a user interface
  48. 48. defining our API can help us be better humans
  49. 49. > myctl contact list --best TO PREFERENCE @mjbrender 1 slack.snap-telemetry.io 2

×