Be The API - VMware UserCon 2016

Be The APIan exploration of careers, supported by code and memes

by @mjbrender

Business Logic

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.”

History of APIs

2000

http://apievangelist.com/2012/12/20/history-of-apis/

Structured input and output

vSphere API

source

https://pubs.vmware.com/vsphere-50/index.jsp?topic=/com.vmware.wssdk.pg.doc_50/PG_Ch2_Programming_Model.4.3.html

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

API is a machine interface CLI is a user interfaceGUI is a user interface

An API says:

Request this.

Get that.

{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, [email protected]

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”: “[email protected]”, “description”: “House on Fire”,“urgency”: “high”}

http://localhost/v1/contact/[email protected]

GET job/skillReturns a list of advertised job skills.

typeoptional

Return the category of work this falls underValues: ENG, MKT, SALES, FINANCE, MGMT


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



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


Boolean preference as defined by the service providerExample Value: true

include_lead_timeoptional

Boolean to include default lead time per requestExample Value: true



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


urgencyrequired


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

Be The API - VMware UserCon 2016

Engineering

Transcript of Be The API - VMware UserCon 2016