What Does a Good API Look Like? A Review Of Slack
API expert Kin Lane deep dives into a review of the Slack API. Whilst not perfect, it provides a good base for anyone trying to understand what @good@ looks like.
Join the DZone community and get the full member experience.Join For Free
I am using my minimum viable API operations definition tool to continue profiling the API sector, this time to size up the Slack API community. Slack is kind of a darling of the API space, so it kind of seem silly to profile them, but profiling those who are doing this API think right, is what API Evangelist all about--whether I follow the hype or not.
Using my minimum viable API definition, I went through the Slack API portal looking for what I'd consider to be the essential building blocks that any modern API platform should have.
|Description:||All of our APIs can be used alone or in conjunction with each other to build many different kinds of Slack apps. Whether you're looking to build an official Slack app for your service, or you just want to build a custom integration for your team, we can help you get started!|
|API Base URL:||https://slack.com/api/|
|Pricing:||You should be at least sharing some rate limits, acceptable uses, and other pricing and access related information.|
|Terms of Service:||https://slack.com/terms-of-service/api|
|OpenAPI Spec:||A machine readable OpenAPI Specification for an API is fast becoming an essential element of API operations.|
|API Blueprint:||A machine readable API Blueprint for an API is fast becoming an essential element of API operations.|
|Postman Collection:||A machine readable Postman Colelction for an API is fast becoming an essential element of API operations.|
|Github Org / User:||https://github.com/slackhq|
Performing better than the review of the i.Materialise 3D printing API that I conducted the other day, Slack checks off all but one of the essential building blocks-everything except for pricing. The only other area(s) that I find deficient, is when it comes to machine readable API definitions like OpenAPI Spec and Postman Collections. These aren't required for success, but they can sure go a long ways in helping developers on-board from documentation, to generating code, and tooling that will be needed for integration.
I'm assuming Slack hasn't generated OpenAPI Specs because they have a more XML-RPC design, which I think many folks assume can't be documented in this way. While it doesn't lend itself to more easily being documented with OpenAPI Spec, I found some simple little hacks that make it doable, allowing you to also document even XML-RPC designs. Having some OpenAPI Specs and Postman Collections would make the API more accessible for people looking to play with.
Anyways, I just wanted to test out the minimum viable API operations tool on another API. I am trying to profile several APIs in this way each week, helping the number of APIs I am monitoring grow, while also encouraging other API providers to follow Slack's lead.
Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.