Developer Portal Considerations

[Amit Shah]

I have a few questions while I am understanding how to host an api developer portal for our api's. Considering that we only have a bunch of api's exposed for internal usage right now, kindly let me know your thoughts to the below queries

1. API Keys - I have seen most of the developer portals require developer registration. This steps generates API keys. As I understand these keys are mainly to be used while testing/debuging api's on the portal. Is that correct? If so, what is actual benefit in exposing such API keys other then user identification. Given that the api's are exposed to internal/private group would it be ok to not have developer registration?

2. Try-it feature - Given that the developer portal would be a single instance deployment for all client deployments, is the developer portal connected to the special api server to which the request are sent when the developer tries out or debugs an api on the api developer portal? The mail goal of the "try-it" button on the developer portal is to generally allow a developer to try out the api with dummy/test data. Can the developer portal handle such requests by itself?

3. Code-snippets - The free/open-source developer portal creation tools I have seen so far are iodocs/swagger/carte. These do not provide a way to share sample code snippets to the developers on the developer portal. Is my analysis right? If so, what could be a way to provide this ability with free/open-source tools.

I would appreciate to hear our expert suggestions on my queries.

Thanks.

[James Higginbotham]

Hi,

Let me try to address some of your questions, as I'm helping a client build out an internal developer portal for their future API platform:

1. Registration isn't necessary to review the docs - in fact, I encourage low friction for those learning about the API. Registration should only be required once they wish to consume the API, via HTTP using cURL/Postman/etc, using code, or from interactive reference docs

2. The developer portal won't handle the API requests itself, you need to stand up an instance of the API or point it at production. The easiest option is to have a single developer portal that offers currently available APIs and points to a sandbox for interactive documentation, as that allows for experimentation without impacting production. The sandbox can have a subset of data from production, perhaps cleansed to remove PII and other sensitive information, or it may be a set of known working data for exercising known scenarios that mimic production. You can get a little more robust if needed by adding in a developer portal per environment, e.g. production and staging, allowing your documentation to point to that specific environment's APIs and reflect what is currently available in those environments. You'll need to script that promotion logic alongside your code promotion process in your CI/CD automation. 

3. I suggest code snippets to exist outside of Swagger, as Swagger (et al) is really for capturing API definitions that can drive reference documentation. The developer portal should offer a high-level view of the domain concepts offered by the API, to help those new to the company or to consuming the API. You can also offer code examples at the same time. Some APIs, such as Stripe, offer examples in various languages alongside the reference documentation, which is helpful for understanding the specific endpoint but aren't always complete enough to demonstrate end-to-end use cases when complex workflows are involved. You need to determine what is necessary to support your target audience, mixing in reference documentation with anything else you need to help API consumers to be successful. You may also want to consider the needs of those outside of development, such as product owners and business leaders that may wish to understand the API's capabilities at a higher level. 

FYI, I wrote up a higher-level view of API documentation that includes links to additional articles and insights, to help with mapping out your API documentation strategy: http://launchany.com/building-your-api-documentation-strategy-for-success/

James

[API Dev]

Thanks James. I appreciate the detailed reply. It really helped me to clear my understanding on API developer portals. I have a few follow up questions that I would like to get your inputs on

Registration should only be required once they wish to consume the API

So registration is basically needed 

1. To understand the client usage - If the developer portal allows a developer to try out code snippets in various languages then we could monitor it to understand what the api clients look like - what language do they generally use. 

2. Block malicious devs - Since we generate the API keys we can automatically block if a developer makes bulk requests to the API and tries to bring the server down. 

Given that our api would be accessed mostly by internal users currently I think it may not be useful to have registration. Let me know if you see other benefits.

 I suggest code snippets to exist outside of Swagger

I haven't done a detailed analysis of comparing Swagger with iodocs, but iodocs look pretty simple while swagger mandates a custom specification to follow. My understanding was that these developer portal building tools do not provide a way to share code snippets. What should we use to do that? Do I need to integrate another tool with the iodocs for that?

Thanks!

[James Higginbotham]

Internal registration is useful for communication of improvements, fixes, etc. but may not be necessary at the beginning.

Regarding the examples and other content, I've seen teams use Github pages, Confluence/other wiki, or static site generators such as Hugo or Middleman to build out the portal, linking to Swagger for the reference documentation. The important thing is to find tools that work with your internal process and that also support the technical writers effectively. 

James