Hosting Your Portal
You can generate and host a Developer Experience Portal from your API in just a few simple steps. This documentation will give you a complete walkthrough of generating a portal from your API description to hosting it on our domain. It will also cover options available to let you host the portal on your own domain. The API we will be using for the walkthrough is the Calculator API.
Generating Portal From Your API Description
On our main website, click on “Developer Experience Portal”. A page similar to the one shown below will open:
Now bring in your API description file either by providing a URL or by uploading a local file from your system. The file must be in one of the supported formats (APIMATIC, WADL, WSDL, Swagger, Open API, RAML, API Blueprint, IODocs, Google Discovery, Mashape, Postman Collection, HAR). Then click on “Generate Portal”.
Our system will validate your file at this point and indicate any errors/warnings found in your API description file as shown below:
If there are any errors found, you will have to fix them before proceeding ahead. If all is good, then you will be taken to the preview of the default landing page of your portal as shown below:
Customize Your Portal
You can customize the look and feel of your portal to look exactly the way you want it to be, before it gets published. Just click on “Customize/Publish” from the pop-up appearing at the bottom of the landing page to start making customizations to your landing page as well the docs.
The default portal type selected will be “Hosted”. Keep it as it is.
Customize Landing Page
The landing page serves as the entry point to your portal and it is important to customize it in accordance with your needs. You can:
- Change the title of your landing page.
- Assign a tagline for the portal.
- Upload a cover image if you don’t prefer to use the default one.
- Upload your company’s logo image.
- Provide a URL to link the portal header to your website.
- Change primary color of the portal.
Note The changes to primary color will affect all pages and not just the landing page.
- Add custom sections to the landing page to provide any additional introductory information.
- Override the default navigational links present in the header (Getting Started, API Reference, Model Reference) by adding your own.
- You can enable/disable badges that appear at the bottom of the portal.
More details for each of these customizations is available at Customizing Your Portal
Change the tab to “Docs”.
The docs section in the portal will contain language specific docs and the HTTP reference doc. You can customize these as follows:
- Choose to keep/remove HTTP docs section in the portal.
- Enable/disable the option to allow users to export to various formats from your portal.
- Enable docs for languages of only your choice e.g. you can choose to disable docs for PHP. You can also specify a link to GitHub repository where that language’s SDK is deployed.
- Add documentation/guides to provide any additional information to your portal users in the docs.
More details for each of these customizations is available at Customizing Your Portal.
Publish Your Portal
Save the changes you’ve made so far and click on “Pubilsh”. You will be given two options for publishing this portal:
- Host this portal on apimatic.io
- Get your portal white-labeled to host on your domain.
Host on Apimatic.io
To host your portal on our domain, you need to provide a unique identifier which is called a “slug”. The slug can contain one or more words separated by a dash “-” e.g. for this walkthrough, we will assign it the value of
simple-calculator-api. Once you’ve decided on the slug, simply click on “Done” and your portal will be hosted on the mentioned URL.
You can view the hosted portal for the API used in this walkthrough at this link.
Instead of choosing to host the portal on our domain, you can get the portal white-labeled and hosted at your own domain. Contact us for further details on this.
Republishing Your Portal
You can make changes to the customizations and other configurations of your portal after it is published, and republish it with the latest changes. Simply click on “Publish” and update the existing version.
Instead of hosting the Developer Experience Portal, you can choose to embed some of its components into your existing portal. Visit the documentation at this link to learn more.
Have questions? Submit a request.