Thanks to all who participated in last week's Webcast, "Applying Universal Design Principles to API Initiatives" in which Kevin Swiber (@kevingswiber) and Alan Languirand (@13protons) discussed applying universal and proven design principles and best practices to your entire API initiative.
The video and slides for the session are below.
There were questions that our hosts didn't get a chance to address during the hour so we follow up on them below. We'd love to continue the discussion on the api-craft forum.
Reference docs vs. User Guides which demonstrate 'how to'? Just to get the key points from you guys on these really. (Phil Leggetter)
There is usually a difference between outlining design patterns/intent, and documenting resource/method terms and how to use them. Provide both for completeness. How-to documentation, such as a Getting Started guide, is often very helpful for onramping app developers to your API platform.
Any suggestions for API documentation generation? Wordnik looked great - was there a tool used for that? (Levi Strope)
Swagger - swagger.wordnik.com
You mentioned to use Oauth for SOAP, is it practice to use in the industry? If the system does not need involve the user credentials ( 2 legged OAuth), is OAuth still good option for SOAP? (Lindy Kyaw)
For SOAP, I’ve seen HTTP basic used, but generally securing this behind a proxy for the public Internet would be better.
Any resources/documentation to refer for an ideal API Layering Strategy? (Rahul Krishnan)
Take tips from object-oriented design. Domain Driven Design has a lot of guidance on this.
If you have to pick a site which has the best API documentation, which one would you pick? (Dharmesh Shroff)
Twilio because of how it relates API error codes back to online docs.
How important are libraries that developers can use to access your API? Most of the examples seem to focus on REST. Maybe RESTful APIs don't need libraries as much as say WebSocket or proprietary/other technologies? Maybe something that needs it's own more 'chatty' protocol. Or maybe something that has workflow that combines multiple API calls or extracting and using information from API response. (Phil Leggetter)
This all goes back to developer delight. If there is demand from your developer base, then this will speed adoption up front, but can potentially slow your update process in the future. There is a definitely a tradeoff here.
Many of the APIs we see today are designed for consumption of a service. Do you see a similar market developing for APIs that allow for the management of services? (Bill Semper)
Yes, potentially. This could be a type of admin interface like AWS. If you can solve combination problems for people, then there may be a market for management services.
I have a few clients that access a central API where they store their data. Their customers in turn access the API through their browsers. What is the best kind of security for controlling access? (John Burrows)
OAuth is a great way to go.
The API console/interactive docs and there was a slide that seemed to cover debugging seem like examples of tooling to help developers. Is that correct? How important do you feel tooling is? We've got 3 examples: online debug console, event creator and library debugging https://pusher.com/docs/debugging (Phil Leggetter)
Tooling is extremely important. A good interface or console really helps. Make sure you think about things from the app developer’s perspective. Consider command line tools if you think your target audience is using that, for example.
How do you measure the impact of API features before you implement them? (Kaj Kandler)
This is about your value proposition. You can’t measure it directly, but it’s the reason you’re bringing an API to market. Ask people - what would like to see here?
How do you measure the impact of API features? (Kaj Kandler)
Decide on analytics up front, level of adoption is a metric. Ask people directly through the chanels you’ve opened up.
How do you weigh good errors with security? Malicious use could derive clues on how to crack with detailed errors. (Greg Guerin)
The detail from those errors need to be human in nature, but not necessarily the details behind the scenes. You don’t want to call out classes or line numbers that are throwing the errors, but rather be topical, such as saying there was a bad authentication token, or a missing parameter.