The second day of Gluecon continued the previous day's emphasis on APIs and better development cultures. However the lack of focused tracks, handful of last-second cancellations, and smattering of off-the-cuff presentations resulted in a more meandering day.
The Case for Application Driven Cloud Computing
Adam Davis, Citi
Throughout the conference, there was a reoccurring image of the developer and operations groups within medium-to-large companies. It was no different with Adam, who got to his image of farm silos early in his deck. Adam lamented the loss of the "good old days" of open systems. During this time there was little separation between development and operations. The devs, systems administrators, and database maintainers all worked on the same team.
All good things are destined to come to an end, however. Rather than jointly herding cattle in the same direction people came to care for their own systems as if they were pets. Companies delegated and defined specific roles within an organization was to achieve efficiencies. But, instead of elegant, pin-point systems the enterprise morphed into fenced off pastures (or, depending on your agricultural metaphor of choice, siloed fiefdoms).
Through heavy standardization and limited variation Henry Ford was able to achieve efficiencies on his fabled assembly line. He reduced the time it took to produce a car from 12.5 hours to 93 minutes, while simultaneously accomplishing the task with less manpower. These efficiencies came with concessions: the cars only came in the color black because it was the only color that could dry fast enough.
"Automation needs to be fit for purpose and not constrained by the procedure it replaces."
Many companies have introduced automated processes into their operations. But, because tearing down fences that have defined boundaries between departments is hard, we now have the same pastures as before, just with robotic cows.
"so what we ended up by automating [four] standardized processes with cloud is four automated silos" - Lori MacVittie
What is missing is the realization that automation should be able to bridge across these artificial divisors. Yes, the robotic cows are more efficient, but it is not victory. If we architect our applications differently for cloud-scale, shouldn't we also re-architect how we host them?
How to Make Things Invisible
Joshua McKenty, Piston Cloud Computing
"Learning to program has no more to do with designing interactive software than learning to touch type has to do with writing poetry" - Ted Nelson
If one is not trying to get better, they won't get better. It is not a matter of acquiring 10,000 hours toward a pursuit, it is the deliberate practice during that time. If we're not uncomfortable during the work we're not getting better.
Writing API SDKs is uncomfortable because, in part, because it makes us consider consuming the API as the client rather than as the API author.
Ignoring things doesn't make them invisible. Many API developers ignore the users. They create distributed systems hooks that make sense to them. But the end consuming clients aren't invisible, in this case; they're just forgotten. And APIs written in this way usually aren't very good.
Affordance is a term used in the design of physical object. It is how we are clued in on how to use an object. It is the way a door handle suggests to us whether we need to push or pull. It is the hint that a baseball would best fit in the hand rather than being sat on. And, in software, it is the messaging on how to interact with the UI. If we have to write documentation on how to use an API then how obvious is the API interface to begin with?
The API is not a natural extension of code. It is it's own product. And it requires the thinking about product presentation the same way care is put into a gadget from Apple or the detail present in a Tesla car. It sounds simple. But, obvious in retrospect, simple is hard to do in the moment.
Being right doesn't matter. Having the "right" API isn't a correct affordance. If a user wants a duck, they should get a duck. Providing an API that offers anatomical duck parts and expecting them to reassemble the pieces from scratch is unrealistic. If a user's mental model expects a duck, it is the job of design to present said duck.
A REST API should not expose objects. It should expose resources. It is important to realize that those two things do not necessarily have a 1-to-1 relationship. Internally you may have a wing, a beak, and a gizzard object. But what is exposed to the consuming client is a duck.
Apple throws out affordances to get to the right affordance. With Piston, Joshua's company, they've thrown out the concept of OS. It doesn't matter anymore. There is no reason to expose that. Simple is the only thing that does scale. Open Stack has a ridiculous number of APIs. And it gets in trouble because of that. It's not even that it offers the gizzards of a duck; it's even more granular than that, offering the API equivalent of muscle, tissue, and blood vessels. In the effort to expose every single nuance that might ever be possibly desired they've created an overwhelming and unapproachable system.
The tension comes from the desire for composability in the future (the ability to remix things during innovation) verses standardization now (ability during maturation). The thing that might be different now is the mobility gap (not in reference to the economic concept, but the idea of the space between where data actually resides in the cloud). It is like making pizza in the 1500s. You can't make a pizza chain in that period because tomatoes were in the new world taking a year for a round trip. You can't ignore the network. Distance can't be eliminated. Today we've solved the tomato problem and pizza chains are everywhere. But the cost of moving data is the #1 bottleneck.
Cloud computing on the edge is a dumb idea. If the edges are as far away as possible (as it will be distributed with the Internet of Things, or IoT) then the gap is huge. It is building a duck with a gigantic worm hole in the middle.
What you care about is the abstraction where you get work done. You don't care whether 120 volts at 60 hertz is an open standard. It no longer matters. Part of our obsession with detail is that we get hung up on levels where we don't need to be.
"Anybody who tells me I can't use a program because it's not open source, go suck on rms. I'm not interested. 99% of that I run tends to be open source, but that's my choice, dammit." - Linus Trovalis
Deliberately try to make a vast portion of what you do invisible. There is no "right way" to do things. We need to be like improvisational performers. In improvisation, there is a rule of thumb that you can't say "no" to anything that is said because it kills the momentum. The solutions that we need to build are "yes and..." solutions.
Taming the RESTed NARWHL - Striking the Balance Between Usability and Zealotry in REST
Rob Zazueta, Mashery
Rob approaches API design from a strategy-first perspective. Part of his job is not only to understand what is happening in the REST space but translating that into practical execution for clients. In talking with the best and brightest in the API space it becomes obvious that we have a problem: there's a discrepancy between those arguing best practices and those charged with getting things done.
Traversal of hypermedia API links is a P-I-T-A. While it may be highest academic realization of hypermedia API design but it is, in practice, difficult to use. It requires a ton of code to "follow your nose". The example provided by Rob is finding an employee's contact information within an enterprise system where all you know is the global resource directory endpoint. First you're required to call that to get the directories for individual countries. Then, once you have the link for United States employees, you have to call that link to get employees for individual states. Then, calling the California employee endpoint, you might be provided with a number of offices; and you still haven't found the employee's email address.
Through work with customers, Rob compiled his experience into the NARWHL framework. NARWHL stands for Noun As Resource With Hyper Links. It is intended for consumption by application built by people. It is the core nouns of a system exposed as resources.
An API should not cause confusion from those responsible from implementing interactions with it. It should be obvious. It shouldn't require research spike after research spike. NARWHL is about creating APIs that people can use now. On the Richardson maturity model, NARWHL starts at level 3 and then goes further.
When developing a NARWHL API start with discovering the possible use cases. This should be a cross-disciplinary action. Your API is a product with all actors involved.
Once you have your resources you can then design your endpoints. Endpoint design matters. Yes, hypermedia allows people to traverse across links but links aren't just a machine-to-machine way of communicating. It is important because of the affordances, the clues, the links offer as to what is going on. We refer to links when we debug. Implementation of links is how we segment labor. Endpoints, and their logical construction, still are vital.
Saner versioning through content negotiation is also possible using NARWHL. To do so API developers should start using specific MIME types in responses — even custom ones. A mime type of "content-type: text/json" doesn't have meaning. As a result information on usage and parsing has to be conveyed in other ways (like documentation). Use something with meaning: content-type: applicaiton/vnd.example.products.json+v1. It's a way of doing versioning without embedding versioning in the canonical resource URL. If you do it like this today then you don't break stuff.
SDKs suck because:
- they're one more thing to maintain
- they often assume functionality outside the API
- they get bloated
The answer to the SDK problem is to have dynamic client generation through response profiles. The documentation of methods, parameters, and models are tightly integrated into the server code, allowing APIs to always stay in sync.
Dynamic code libraries rock because:
- they reflect only what's defined in the API
- they grow and change as the API iterates
- they feel more native to the developer
By using a API definition with a common standard (swagger, RAML, HAL, etc. ) dynamic code libraries are possible. The one thing SOAP did well was WSDL. Every language had something that could generate code if given a WSDL. We should get to the point where we are able to auto gen code from an API definition in any language that best suits our task.
Rob wants the best for REST APIs. But he also wants those who are under deadlines not to get tripped up on academic minutia. NARWHL is an attempt to walk the line between strategy and practice.
After the Breathlessness: What we Need to Figure out About IoT
Lorinda Brandon, SmartBear
Lorinda began her talk by stating her mission was to represent non-technical America to the conference. The reality is that most have been interacting with the Internet of Things (IoT) for quite some time (connected gas pumps, onStar which is a connected car). Despite this, the average consumer wouldn't consider those experiences revolutionary or out of the ordinary. They quietly just became the way things were done.
Why is the IoT way different? For the first time these always-on, connected devices are coming into our homes. What does it mean to be a consumer experiencing a connected device in their home for the first time?
The promise of this new wave is an Internet not of stuff 'out-there' but of "my things". Food starts prepping as I approach home, the lights come on, and the music may start playing. The promise is that our things will understand us and our needs, that our immediate world will be modified by these things to reflect our preferences and desires. We will have a relationship. We want our stuff to love us.
What is our current relationship with "smart" things? We buy them one at a time. We love them individually (a NEST, a Sonos, a fitbit, etc.). Lorinda has a tension with the NEST because it is in a room rarely accessed, and thus, never thinks she is at home. A Sonos only allows for one relationship at a time; among her family they haggle about who's account is active at a time. The preferences and desires by which to augment the immediate world clash when there are multiple people inhabiting it.
These connected things are very disconnected with each other. Worse, we don't trust the connected things we put in our homes. We don't know the data collected (suspect that it is different than the data we're allowed to see) and we don't know who owns that data.
Developers only focus on the possibility of IoT. Testers, however, are still struggling to come to grips with testing mobile. Now we're throwing these devices into the mix. To succeed with this exponential bump in complexity IoT devices (and the APIs that support them) need to be:
- simple
- discoverable
- secure (it's our responsibility, both systems and data, we have to do the right thing while the law catches up)
- testable (if it can be made testable we can solve a lot of the other problems)
The speed to market is not as important as the integrity of product.
10 Reasons Developers Hate Your API (and what to do about it)
John Musser, Programmable Web, API Science
If you want to entertain yourself, Google "API Sucks". The warning sign an API sucks is when people ask "can you just send me a CSV?" in order to get the data they need.
So why would people hate your API? And, more importantly, what can you do about it?
- Your documentation sucks. How do you fix it?
- Keep the big picture in mind, seeing your API from the viewpoint of someone brand new.
- Be clear
- Provide Find-ability
- Use Live Docs auto generated from machine descriptors
- You communication skills need work (you need to keep your developers informed, otherwise your changes lead to breakage)
- Post a Change Log for an API
- Publish a Roadmap for what to expect
- Update Release Notes (how do I know whether to care about a change?)
- Blog about Changes
- Engage Forums (doesn't even have to be your own, like SoundCloud using Stack Overflow)
- Write Email (targeted, non-marketing speak)
- You don't make it easy (no hello world, getting started guide, nothing to copy & paste)
- Provide fast signup (get a feel with 0 committment)
- Illustrate process with the 1-2-3, a conceptual wizard for getting started to inform on entirety of process from beginning to first win
- write quickstarts
- allow for free & trial tiers
- if possible, publish and maintain copious SDKs
- use GitHub (samples made available for forks)
- Lawyers are running show (seen with commercial restrictions, no SLA, rate limiting, overwhelming reams of legalese)
- be clear (500px publishes legalese alongside plain English)
- set the tone (etsy terms-of-use beautifully frames the terms of service with clear intentions)
- shorter = better
- think long term - offer assurances of how long service will be provided. Create a deprecation policy so that those building on an API know what to expect.
- share the wealth and articulate business model
- You API is unreliable (or buggy or inconsistent)
- communicate health through a status screen or dashboard
- monitor performance
- don't hide if something bad happens, own it
- You don't give tools to succeed. (How do I debug? What's my usage?) Provide:
- dev dashboard
- debug/log, what's happening from the API veiwpoint
- test sandbox
- playground
- test console
- you're marketing to me, not helping me
- evangelists (help, don't pitch)
- events
- hackathons
- your api is too complex (or you have your own custom, or insider knowledge)
- use REST
- use json
- be pragmatic, don't over-engineer it
- your time to first 'hello world' (TTFHW) is too long (how long to zero to 60?)
- craft great DX (developer experience)
- incorporate all prior fixes - that is a part of developer experience
- You haven't learned from the best
- use role models - twilio, stripe, github, sendgrid
- keep learning
- understand that a great API is a journey, not a destination
APIs.json and API Discovery on the Web
Steven Willmott and Kin Lane, 3Scale and APIEvangelist.com, respectively
The problem that they set out to solve with APIs.json is that:
- there is an increasing number of APIs
- which rarely use a machine readable format to describe them
- no obvious place to publish/find them in a machine manner
- API consumers aren't able to create classes of tooling across APIs, for example, something to crawl the 'web of APIs'
- API publishers have to self-report and replicate data everywhere in niche silos (on programmable web, on own site, on custom aggregators like mashape, in specialized directories, etc)
Kin started, in his work with the federal government, to place a '/developer' subdirectory at every government office. In the same way a '.gov' TLD is a clear indication a website is government-approved information, a 'developer' directory would be a known point providing machine readable hints we wouldn't have to think about. This work subsequently lead to the definition to "data.json" file being expected at the top level of government domains. Now the effort is to extend beyond government mandates and become a grass-roots standard among API publishers.
With this simple, self-published format we can now create tooling to aggregate these things. An example tool is the search engine on APIs.IO. Unlike API aggregators that have come before, APIs.IO is not a repository for data. API creators only need to add link to APIs.json file and the search engine will subsequently crawl what it finds there. The site also has an APIs.json builder. Developers can put in some properties and the site will help write the file. There is a common glossary of link types to be included in the docs. The repository of these is available on Github and open to discussion.
APIsjson.org is the site to find out more about the API format. Think of the APIs.json format as the equivalent of a machine-readible sitemap for an API.
