Post on 16-Apr-2017
Be The APIan exploration of careers, supported by code and memes
by @mjbrender
Business Logic
The Happy Place
The Happy Place
My Less Happy Place
No, Not Again
“Hey, Sisyphus, when you’ve got a minute I’d like to discuss this progress report with you.”
> cd $HOME>>> bash ./admin_scriptfixing foo
> vim ./admin_script
cmd | xarg –n 1 sed –i “s/server/foo/g” | grep -i up >err.log 2>&1
“An Application Programming Interface is a set of routines, protocols, and tools for building software applications.”
Structured input and output
vSphere API
source
Many Other APIsJSON
JSON
is the API the new CLI
?
> cmd
| grep | sed | awk
the API the new CLI
(if and only if you use the CLI like this example)
> cmd
| grep | sed | awk
JSON
JSON
JSON
JSON
API is a machine interface CLI is a user interfaceGUI is a user interface
An API says:
Request this.
Get that.
{you}
{myapi}
serverAPI
myctl
{myapi} service
GET job/Return a description of my job.
There are no options available for this endpoint.
> 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.
GET contact/Returns a list of available forms of contact.
typerequired
Return whether the contact is personal or professionalValues: personal, professional, all
include_preferenceoptional
Boolean preference as defined by the serviceExample Value: true
include_reply_timeoptional
Return average response time for requestExample Value: false
Response formats JSON
Requires authentication? No
Rate limited? Yes
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", } ] } }
> myctl contact list --all
TYPE PREFERENCE REPLY TIMEemail 2 3dtext 3 1mtweet 1 30scall 4 5d
PUT contact/[:to]Request that gets in contact with the API owner. Returns string response to the request.
fromrequired
Return location appropriate for the endpointExample Value: @mjbrender, mjbrender@gmail.com
messagerequired
Reason for the contactExample Value: “Thought you’d like this post”
urgencyoptional
Definition of how quickly a reply is required.Values: Low, Medium, High
include_lead_timeoptional
Boolean to include approximate time to respond.Example Value: true
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.” }
{ ”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
GET job/skillReturns a list of advertised job skills.
typeoptional
Return the category of work this falls underValues: ENG, MKT, SALES, FINANCE, MGMT
include_preferenceoptional
Boolean preference as defined by the service provider. Defined on a scale from 1-7 with 7 as most preferredExample Value: 3
include_leveloptional
Boolean level of expertise of the service provider. Expertise is defined on a scale from 1-7 with 7 as bestExample Value: 7
Response formats JSON
Requires authentication? No
Rate limited? No
> myctl skill list --type=ENG -p
SKILL TYPEPREFERENCEBuild Automation ENG 5Product Mgmt ENG 5Dev Mgmt ENG 4Traditional IT ENG 3Cloud Native ENG 7Ruby Developer ENG 3Go Developer ENG 3
> myctl skill list --type=ENG -p
SKILL TYPEPREFERENCEBuild Automation ENG 5Product Mgmt ENG 5Dev Mgmt ENG 4Traditional IT ENG 3Cloud Native ENG 7Ruby Developer ENG 3Go Developer ENG 3
> myctl skill list --type=ENG -l
SKILL TYPE SKILL LEVELBuild Automation ENG 2Product Mgmt ENG 5Dev Mgmt ENG 4Traditional IT ENG 5Cloud Native ENG 3Ruby Developer ENG 2Go Developer ENG 2
> myctl skill list --type=ENG -l
SKILL TYPE SKILL LEVELBuild Automation ENG 2Product Mgmt ENG 5Dev Mgmt ENG 4Traditional IT ENG 5Cloud Native ENG 3Ruby Developer ENG 2Go Developer ENG 2
> myctl skill list --type=MKT -l
SKILL TYPE SKILL LEVELPowerPoint ing MKT 6Podcasting MKT 6Blogging MKT 4Public Speaking MKT 4Product Messaging MKT 5Logo Design MKT 5Social Media MKT 5
GET job/request/Review active work requests with expected completion dates.
typeoptional
Return the category of work this falls underValues: ENG, MKT, SALES, FINANCE, MGMT
include_preferenceoptional
Boolean preference as defined by the service providerExample Value: true
include_lead_timeoptional
Boolean to include default lead time per requestExample Value: true
Response formats JSON
Requires authentication? No
Rate limited? No
> myctl work list -t -lt
REQUEST TYPE LEAD TIMECreate PPT MKT 7dDefine OSS Release ENG 5dTest Automation ENG 3dWrite Blog Post MKT 2dRe to Sales MGMT .5dSchedule Meeting MGMT .25dCreate other PPT MKT 7d
PUT job/request/Request that gets in contact with the API owner. Returns expected response time.
titlerequired
Boolean preference as defined by the serviceExample Value: true
descriptionrequired
Return average response time for requestExample Value: false
urgencyrequired
Return average response time for requestExample Value: false
authorizedoptional
Return average response time for requestExample Value: true
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/
GETcontact/job/job/skill/job/request/
PUT contact/
job/request/
{myapi}
What’s undocumented?
Endpoint
GET hobby/
Options
tone := Reflect.type(tone)
An API says:
Request this.
Get that.
API is a machine interface CLI is a user interfaceGUI is a user interface
defining our API can help us be better humans
> myctl contact list --best
TO PREFERENCE@mjbrender 1slack.snap-telemetry.io 2