Mehdi Raza Jaffery March 22, 2018

Revamped HTTP docs on API Portal

The fight for improving the Developer Experience in API portals is not over yet!

In fact, we have just released a major revamp of HTTP documentation to all our customers. ?

Let’s see the new features in detail.

New Curl Examples

Our HTTP docs now show an API console with Curl commands for each endpoint.

What is Curl, you say?

It is a nifty tool for making HTTP calls from the terminal, popular with developers. Curl can be installed on Linux, MacOS and Windows.

Here’s what a simple Curl command looks like that sends a GET request along with an Accept header:

curl 'https://demo.api-platform.com/books' \ -H 'accept: application/json'

What’s in our Curl Examples?

Our API portal uses examples from the API description file to create Curl commands which are then shown in the endpoint documentation.

Curl Example
Curl example for sending an API call via Telstra’s API

Check out how the Curl command contains all the right headers; it even caters to API authentication and the body format of the request.

In fact, the Curl examples fully integrate with the API Console letting the user change the endpoint parameters while those changes are reflected in the example live.

 APIConsolelettingtheuser

The user can just copy and paste the Curl command in their favorite terminal to run it.

Improved Authentication docs

Our Authentication section now shows detailed docs for common authentication types such as HTTP basic, OAuth 2, and custom API keys.

These docs include Curl examples so that the users can try them out in the terminal. Check out this example for an API that uses OAuth 2 Client Credentials grant:

Authentication Docs
Example of auto-generated Auth docs

All of this is auto-generated from the API definition file!

⭐️ Can your Portal do this?

Our API portals have:

Give our portal generator a try!