We partnered with API Evangelist to launch in 2014 the apis.json
format at Gluecon. The idea is to build something as simple as robots.txt
for websites but for APIs.
It does not matter the language used to build the APIs, on which platform it runs or which container it runs.
With the launch of APIs.json
we also launched APIs.io, the search engine for APIs.
Now we are happy announce you can have a similar experience on your developer portal.
Being able to list all your apis, and let your users search easily through them.
You can see a working demo below:
- 3scale account with Developer Portal
- a Swagger spec (3scale ActiveDocs) for each service
You already have an APIs.json file to describe your API? Genius! you can already move to next part.
If you are not familiar with this format I encourage you look at the specification first.
To build your file you can use the builder available on APIs.io or any IDE to produce a .json
file.
For our tutorial we will use this sample file It has two APIs: Voice API, and SMS API.
As you may have seen, we have added vendor extension X-3scale
. You should add it to each API contained in your apis.json
file.
Like the following:
"X-3scale":{
"service_id":{THREESCALE_SERVICE_ID},
"swagger_system_name":"{THREESCALE_ACTIVEDOCS_SYSTEM_NAME}"
}
Replace THREESCALE_SERVICE_ID
by the corresponding ID.
And replace THREESCALE_ACTIVEDOCS_SYSTEM_NAME
by the system name of the ActiveDocs.
Once you are done, you will be ready to upload it to your developer portal.
Go under Developer Portal
section.
Create a new Page named apis.json
, it has to be under Root
section.
Under Advanced options
:
- Change content-type to
application/json
- Make sure liquid tags are disabled
- Make sure layout filed is blank
This file will now be available on this URL https://YOURDOMAIN.3scale.net/apis.json
We will now create a new page named apilist
.
We recommend to place it under Root
section.
You can copy paste the content of apilist.html from this repo into the CMS.
Under Advanced options
:
- Make sure liquid tags are disabled
Save and preview, you should see your list of APIs, a search box and the categories on the right.
We will now add the page apidetails
to display more details about each API.
This page will be displayed when user clicks on an API block in the list, they will be redirected to /apidetails?service_id={SERVICE_ID}
.
- Create a new page
apidetails
underRoot
section. - Under
Advanced options
: Enable liquid tags - Copy paste content from apidetails.html
Data for About
and Documentation
sections are loaded dynamically from apis.json
file.
Other sections have placeholders that you can easily modify, they will be common to every API. If you want to make them dynamic for each API, add more fields under X-3scale
section of apis.json
.
Your discovery experience is now ready :) Congrats!
The look and feel could be customize using Bootstrap CSS framework.