Last week, Tony Blank the Senior Developer Evangelist at Sendgrid, graciously facilitated a hot topic at our All Things API Meetup around the Consumption of APIs. We brought some of the brightest minds in the business, Dan Corbin Product Manager for Context.IO, Shelby Switzer Software Engineer at Healthify and Rocky Madden Engineer and Open Source Evangelist at Cloud Elements. The panel openly discussed topics relevant for both API consumers as well as what it takes for an API provider to bring an API to market. Bad APIs don't get consumed!
Q: What factors should you think about when connecting to 3rd parties?
Corbin leads with - “From a project manager perspective, make sure the developers you intend to be consuming your APIs have an easy on boarding experience. Needs to be easy for them to get support; to get code samples; to access the use cases that help developers to understand how they need to interact with your APIs.”
“I think it’s really exciting for consumers of APIs,” shares Switzer, “because so many APIs are coming to market and are now available to for the public to use, that as consumers you can demand to have higher standards for your APIs.”
Madden chimes in with, “If you’re building a business around an API be cognizant for that fact [previously mentioned by Switzer]. Consumers are expecting those higher standards. For example, it seemed like overnight Twitter closed their API off to the public, without preparing for the consequences of how that would impact the rest of the community. As you design your API, be mindful of how that might effect the greater community.” You have to build trust within your community, so there isn’t the fear that you’re not going to pull the rug out from underneath them.
Q: Fairly hot topic in the community - Should we being using SDKs or not?
Switzer starts out boldly, “I hate SDKs. All jokes aside, as a developer usually SDKs are terrible, because they are not supported and they are so abstracted from the APIs, and there will come a point that when I’m trying to learn about your API, I’ll just give up and stop trying. If you want to use an SDK, make sure it’s open sourced.”
Madden adds, “Whether it’s an API wrapper; SDK or open source, if it’s done well, it can be a beautiful thing. That means you’re consistently maintaining it and testing it. I can totally get onboard with SDKs, if they’re done right and add to customer value. Be sure as you’re designing your SDKs that you keep in mind they are fully capable of running the API into the ground.”
“So our developers really prefer to use SDKs,” says Corbin. “If it is not well maintained you’re doing the developers and clients a huge disservice. And sure we’re guilty and our own SDKs could be better polished, it’s just a matter of balance our priorities. So this makes me wonder if there are services out there that auto-generate SDKs from Swagger will bridge the gap.”
“If you’re going to have an SDK, then your developers need to use their own SDK. I think you should treat it as better than average. It’s like the “eat your own dog food” metaphor. Take Twitter for example, when they have the wrappers, that they need to use themselves,” says Madden.
Blank wraps up with, “Take a hybrid approach. There should always be a purpose for an SDK, so before you put it out there, really try figure out what you’re trying to do. Another idea, you could use an SDK to figure out how the API works, and never actually use the SDK in production.”
Q: As a consumer, what apis have you seen recently that are exciting?
Switzer adds in, “My example is a classic. Twilio’s api is really nice. The Dropbox API gives me warm fuzzy feelings. I like both of these because they’re standard, reliable, no surprises. Twilio’s markup language, also, is pretty exciting.”
Audience: “I need easy to use; I’m smart but not that smart — Take M2X for example, the IOT API by AT&T. With this API you write one time and then replicate across tons of different devices ..For someone that’s not particularly talented, it worked really well. Great functionality, great documentation.”
Q: How much do semantics influence your architecture?
Blank leads in with, “It’s really difficult to know exactly what will work with what. If you’re trying to adhere to a hypermedia format, it might not fit your use case of all your users, across the board. So, it’s difficult to know the semantics — In my opinion, one of the best things you can do is create an architecture with micro services, which is much easier than having one single architecture.
Corbin chimes in, “I wouldn’t consider myself a futurist, but I think there is going to be a lot more powerful APIs coming soon (e.g. GRPC). All the different ways that data are being exchanged, and all the ways that are not yet being exchange, joined up with a lot of IOTs discussions, leads to, well, a very forward-looking conversation. I teach a Product Management class at General Assembly, give my students test and books to read, and all of them can’t believe how many jobs are out there, that are app providers needing to publish their own APIs. What we need to do is figure out how APIs will be exchanging data, beyond computers and computer systems, before we know how to influence your architecture.
Switzer continues on the notion of IOS, “I think every”thing” will have an API. There is just so much happening in this device and connected thing space. If I come across something that doesn’t have an API — I’d honestly feel surprised.”
Madden concludes, “Over time, we’ll see over time a more correct approach to how APIs are being developed. As it gets more pervasive, we’ll see more structure on how they are developed. Slack, for example, has a great API and a web socket API — so you can see what powers the APIs, it’s a really interesting concpt to see how it works.”
Q: What’s the most common mistake MADE WHEN YOU TAKE YOUR 1ST API to market?
Switzer jumps in, “They don’t have rate limiting. Seriously, your API needs to clearly communicate what limits a user has. Have the API respond back.”
Madden agrees and shares, “Agreed. Build in X-headers that tell you where you’re at, when to anticipate when you will run out. When designing the API, often we see that the business will be thinking about how they might score the data in the database (not how the consumer will use it). We need to treat everything like one big bucket of data.”
Q: Why’s it bad to marry your API to your data with usage data?
Madden: “People automatically presuppose the mimic of the backend data infrastructure, which then leads to crowds of V1 APIs disappearing. Decoupling is a good thing, as a one-to-one relationship is not very elegant. View APIs as lenses to dig deeper into your data. Consider that each paradigm will be different based on a use case … A lot of times I see V1 or V2 APIS that I consider V0 — Knowing that that’s a major pattern, I recommend having a limited number of end users trying out your APIs, before you release in a major way. You might then see less of a half-hearted effect to how things are done.”
“APIs are contracts. people are relying on that consistency” Rocky Madden, Open Source Evangelist, Cloud Elements.
Switzer jumps in, “I fully agree. In the past, I have used an API blueprint to mockup what we think our API should do, then get feedback from a developer focus group. It’s a much more rapid process to get feedback from our users. What might have taken weeks to do, we trimmed down to within 30 minutes. For us, at least, it’s a really successful iterations of the APIs and a fast way to get past Version Zero.”
Q: Perfect REST vs. Practical REST?
Corbin leads in with, “Resource link in the body vs. link header, when is it OK to deviate?. Depends on your use case, depends on the consistency and depends on the semantics of your API. Your goal should be just to make your API as consumable as possible. Think about the end user. Think about their use case. Think about the most powerful design from that.”
"One of the most common arguments against truly RESTful is it’s not best suited for mobile, but there are always options to mitigate that use case,” says Switzer.
JOIN US FOR NEXT ALL THINGS API MEETUP IN FEBRUARY!