Be The API - VMware UserCon 2016
•
0 j'aime•321 vues
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.
Recommandé
Recommandé
Contenu connexe
Similaire à Be The API - VMware UserCon 2016
Similaire à Be The API - VMware UserCon 2016 (20)
Plus de Matthew Broberg
Plus de Matthew Broberg (10)
Dernier
Dernier (20)
Be The API - VMware UserCon 2016
- 1. Be The API an exploration of careers, supported by code and memes by @mjbrender
- 8. My Less Happy Place
- 10. No, Not Again
- 12. “Hey, Sisyphus, when you’ve got a minute I’d like to discuss this progress report with you.”
- 13. > cd $HOME > > > bash ./admin_script fixing foo
- 16. > vim ./admin_script cmd | xarg –n 1 sed –i “s/server/foo/g” | grep -i up >err.log 2>&1
- 17. “An Application Programming Interface is a set of routines, protocols, and tools for building software applications.”
- 23. is the API the new CLI ?
- 25. > cmd | grep | sed | awk
- 26. the API the new CLI (if and only if you use the CLI like this example)
- 27. > cmd | grep | sed | awk
- 28. JSON JSON
- 29. JSON JSON
- 30. API is a machine interface CLI is a user interface GUI is a user interface
- 31. An API says: Request this. Get that.
- 32. {you}
- 34. {myapi}
- 36. GET job/ Return a description of my job. There are no options available for this endpoint.
- 37. > 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.
- 38. 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
- 39. 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", } ] } }
- 40. > myctl contact list --all TYPE PREFERENCE REPLY TIME email 2 3d text 3 1m tweet 1 30s call 4 5d
- 41. 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
- 42. 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.” }
- 43. { ”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
- 44. 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
- 45. > 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
- 46. > 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
- 47. > 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
- 48. > 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
- 49. > 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
- 50. 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
- 51. > 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
- 52. 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
- 53. 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/
- 55. What’s undocumented? Endpoint GET hobby/ Options tone := Reflect.type(tone)
- 56. An API says: Request this. Get that.
- 57. API is a machine interface CLI is a user interface GUI is a user interface
- 58. defining our API can help us be better humans
- 59. > myctl contact list --best TO PREFERENCE @mjbrender 1 slack.snap-telemetry.io 2
Notes de l'éditeur
- How do you know you've correctly configured a server? When there’s no error messages saying CRITICAL or someone saying “something is off here” how do you fix it? How do you know a server is misconfigured. Or a switch. A new storage array?
- You do it through business logic. You decide, based on what you know of the environment, what others have stated as the desired state. Based on your years of expertise and knowledge of every vendor under the sun. You’re not scared of mapping spindle to LUN to VM. You’ve conquered the art of subnets. You’re not scared of ANY stack because you know the fundamentals across every system are just that, the fundamentals.
- On those days you do need to configure something, you are just a URL away. For a while, the world felt at my finger tips once I was logged into vSphere. Everything made sense in there. Need a new Windows Server – you got it. New requirements for the Dev cluster: no problem! (it took a while after C# client went away, but we all know that feeling).
- And that was good, because there was always a problem to fix – business logic that needed implementation.
- And it was no problem – one login, a few clicks and I got the work done, no problem.
- And again: hop right in and fix it. No issue.
- At some point, the joy of hopping into vSphere to configure something fades away. Or, more likely, you have so many other GUIs to sign into you start to lose your familiarity with where to fix the problem, but I was still asked to get all that work done.
- It feels futile at some point – pushing the same rock up the same hill only to watch it roll back down again.
- And for many, the questioning of how you use for your futile tasks is being scrutinized. You’re pushed to do more with less or some other business phrase.
- So you evolve: The CLI is the next frontier. Keeping a set of scripts around that can automate some of those guaranteed-to-repeat-themselves tasks. Scripting has done us well.
- After what feel like endless requests to you, your boss wants you to start fixing this proactively instead of reactively.
- The old lines in the sand between one team and another are less acceptable than they previously where. Your boss needs you to DevOps harder.
- You look through the script you’ve relied on up to this point and see that you’re manipulating output from a command line, passing around unstructured output and parsing it over and over again in a barely legible way. (that’s assuming you didn’t write it in perl) THERE HAS TO BE A BETTER WAY
- Provides a structured means of communication from machine to machine
- Social platforms published APIs for consumption Infrastructure continued on its way of the CLI cloud computing changed that.
- It all changed once you could start configuring servers and the applications we run on them through public APIs. Slowly but surely. Every piece of the datacenter – the atomic pieces like CPU, Memory, Disk, Network devices and up the software stack layered on top of it – all uses APIs and they are more and more public of late. Why is it so popular??
- The information returned is in a known format that can be predictably parsed. A documented API Input format (XML, JSON, gRPC, ...) Output format (XML, JSON, binary) Have syntax – the format of a request The parameters that may be required or optional Have methods – functions you can make of the request Have inheritance, protocols like gRPC, formatting from SOAP to REST, client libraries in different programming languages and more, but that’s not what I care about There’s expected input and expected output
- Taking a look through the vSphere API will show that it uses the IETF standard called SOAP to communicate from client to server and back again. Information is encoded in XML objects.
- While many other APIs these days pass another formatting called JSON to HTTP endpoints following REST, which is a set of principles that map really nicely to the HTTP protocol.
- Should we abandon the CLI?
- NO. A CLI is another consumer of the API. What’s nice these days is that both the CLI and the API are opening up, allowing both to be programmatically used for business logic.
- So, I suppose there’s a counter argument to saying no here: If you use the CLI for machine to machine communication, then take the returned values and pipe, grep and awk your way through them, then fine. You can say it.
- The API is the new CLI... not because of its ability to query for the right information but for the fact it accepts and returns is in a known format that can be predictably parsed.
- If we put ourselves back into this equation, running a command over CLI is a perfectly valid way to explore the state of our server.
- If you do want to use an API for your laptop, that’s great! Power to you, it’s just gonna be a little more challenging on the eyes to read. It should not be the goal however.
- The goal is to have machine to machine communication over the API. That can be as simple as a script that leverages an API + cron or as cloud native as an ephemeral container or lambda function. It doesn’t matter as long as it gets the business logic done in a timely way.
- To be extra clear here: the API is for machines. The CLI and GUI continue to be for you and me when we need them. They’re not going away nor should they.
- It’s the simplest type of contract we have in this world. A structured agreement, in whatever format you want for any kind of resource you can request. I ask for something, you give me something in return.
- Which brings me to you. What’s your API? What can someone request from you and what can they expect in return?
- I’m part of a podcast called The Geek Whisperers and we had the pleasure of talking to people at the Silicon Valley VMUG about their careers. We had a line the entire day. I truly don’t think that had to do with us, it had to do with the incredible gap we have as a community when it comes to thinking about our careers. What really struck me about this experience was how everyone – absolutely everyone – can benefit from this conversation about how they communicate their job and the skills they have.
- Having that experience and my continued desire to be a better developer, I thought to start what I’m calling the {myapi} - it’s a thought experiment right now. I see value in each of us exploring the boundaries of our own APIs – what they include and what they’re missing. What we expect from others and what we expect to provide to them. To start by example and walk you through a few career conversations I’ve been having with myself lately, I started to map my own.
- The simplest command has no options – it’s just an endpoint you can make a request to.
- From the CLI tool that uses this API, we get this output. << Read >> This is how I explain my work to others inside the company. Having this one-liner on the top of my head has made all the difference in how I help colleagues see what I can do for them.
- So let’s say you want to get in touch. Here’s an endpoint that returns contact information. Again, the API definition is totally independent of the content returned – that’s the clear line between frontend and backend of the application. To simplify, I’m showing you both as if both are completed.
- by CURLing this URL, we talk to the endpoint and make a request to the method I just showed you. Valid JSON object is returned with all the forms of contact I have.
- Since we discussed how a CLI is just a more user friendly view of the same API output, here’s a prettier version of that information including the optional returns I mentioned before. When I’m honest with myself and my coworkers, my reply times and preference direct users toward Twitter. I own that – I ask people to tweet me instead of email all the time and it’s changed the way I monitor communication.
- Let’s say someone does need to get in touch with me. They’ll perform an HTTP PUT command with the required options included. What information do they have to have?
- Now it’s time to share what I’m good at. Some interesting options for such an endpoint include what type of work is it, by org chart definition. What’s nice about Org Charts as a categorization is that it leads directly to what kind of job I should pursue. That’s an API that gives me more than information, it gives me direction. I add management as it’s own type value since it is a skillset I work hard on developing even while I’m an individual contributor.
- The toughest fact I face when ranking my skills is that I can quickly see my marketing skills are significantly greater than my engineering skills. That’s been a constant challenge for me: do I accept that I could be a great marketer, or do I grind harder to be a better engineer? The verdict isn’t out on that one, which is why I appreciate being a Developer Advocate while I think this through.
- Next we turn to talking about what work I do – I want to provide an API by which anyone can see what I’m working on.
- When I admit, like all other people, that I am not good at multitasking, I can start honestly showing you how long it will be until I complete a given task and that’s if these priorities stay in order. What I do by showing you and others this output is I give you the context to understand what interrupting my current work will do to other work. I love that democratization of context.
- Let’s say you do have work to ask of me. How do you ask it? You’ll see here that if you’re going to assign me work, I expect a lot of optional information before I consider it a valid request. I need context about the work, and I now require the urgency of that request to be explicitly stated. When I assume anything said “not urgent” is lower priority, I find myself having issues. So it’s now a requirement.
- The optional information required, along with the other API endpoints I offer, gives people meaningful responses based purely on the content of their request. Ideas to help – The Three D’s: Deal with; Delegate; and Disappear
- So there you have it – that’s myapi. I have a clear definition of how to get in touch with me. I can clearly explain my job, the skills I have that relate to that job and even my preferences for types of work. I also expose what I’m working on and let others add to that queue of work explicitly.
- The first question I wondered after completing this exercise is: what didn’t I document? I didn’t share my hobbies, which I’ve found valuable to share with my coworkers. I’d like to think through this one next. There’s also a hidden option on each PUT request that I write here in Go pseudocode.
- An API is an explicit definition of expectations for two systems. The “how” is behind the API. People just care about the what – what can I expect from you based on my request.
- It’s normally machine to machine
- Help us be better employees, colleagues, friends and family.
- Since we discussed how a CLI is just a more user friendly view of the same API output, here’s a prettier version of that information including the optional returns I mentioned before. When I’m honest with myself and my coworkers, my reply times and preference direct users toward Twitter. I own that – I ask people to tweet me instead of email all the time and it’s changed the way I monitor communication.
- Comments: “But I don’t know exactly what my job entails” I hear you. I’m not sure either. But it’s time to start owning that choice and recognize it’s ours to negotiate We will still use GUIs and CLIs Human decision making is still needed See beyond the UIs we’re used to and start noticing that our favorite tools – proprietary or open source – are software. And it’s simply not true that you must have a CS degree to code You code. Be proud of it. Make your jobs better. No one cares which of these routes you use to solve the problem. The “how” is behind the API. I just want the what. Your goal, for your own career progression, should be to remove as much monotonous tasks out of your life as you can If you don’t, you’ll spend all your time on behaviors that add very little value OR you’ll hate your boring job OR both