Skip to main content

API Portal FAQs and Troubleshooting

FAQs​

My API is in the design phase, how can APIMatic help me?​

Publishing an API Portal will help getting feedback on the API while it is being designed, and the API can be improved based on the feedback. Furthermore we have a team of API experts that can help out with best practices when it comes to API Design.

How is the developer-centric documentation generated?​

APIMatic takes your API specification file to automatically generate an API portal as well as SDKs for your API to facilitate users that want to consume your APIs.

I imported my API into APIMatic to generate an API portal. Is my API publicly available to the world?​

No. Upon importing the API, your API will be in preview mode and will only be available to you and your team members. Once you want to make your API public, you can publish it using the guide here.

How can I add custom content into the portal?​

You can add the custom content through the Markdown editor in the portal editor. We support a subset of GitHub Flavored Markdown along with the support for hyperlinks, gifs and images. You can create multiple pages and create a hierarchy between them with nested sections and pages.

Are custom guides all markdown?​

All the custom guides are written using subset of GitHub flavored markdown.

I have multiple API specification files and I want to have a single API portal and SDKs. What are the options?​

You can use our API Merging feature to merge multiple API specification files into a single master spec which will then be used to auto-generate a single docs portal and SDKs for your APIs.

How can I arrange my endpoints in the documentation portal?​

Endpoints are arranged based on the order in which they are written within the API specification file. You can change the order of the endpoints by rearranging them in the API specification file.

Can the portal be put behind a login?​

You can take the embedded version of the portal and embed it behind your own login mechanism.

When/why should I go for a self-hosted portal offering?​

It is secure since no network calls are made to APIMatic or any other servers. Everything required to render and make the portal work is provided. You can do the following:

  • Have custom authentication, authorization, usage limits, rate throttling, etc. on it.
  • Place it behind a firewall.
  • Customize it however you want.

All the HTML, JavaScript, and CSS files are provided and are customizable. You can host it in whatever environment and server of your choosing.

How does versioning work in APIMatic?​

You can have multiple versions of the same API hosted in the same portal, with a version selector. APIMatic generates a separate portal for every version.

APIMatic is adding random values to my required parameters in the code samples, what should I do?​

To make sure that the code samples and the SDKs are runnable right out of the box, all required parameters should have a value. To ensure this, APIMatic adds random example values for required parameters if no example value is added in the API specification file. You can overwrite this random example value by passing valid examples for all your required parameters in the API specification file.

How can I change the color theme of my portal?​

You can rebrand your portal and choose a color theme of your choice through our portal editor. You can also customize other areas of your documentation portal and you can read up all about our portal customization options here.

How can I disable the “Export API Spec” button?​

You can use our portal editor to disable the option to export the API specification file. You can also choose between the formats you want to allow the users to export the specification file. You can find complete steps on how to do this here.

You can use our content-referencing feature to hyperlink your content. Content-referencing uses permalinks which work for the specific language that the user is currently working on so if you are scrolling through Python documentation, the hyperlink is going to open that link in Python documentation.

Does APIMatic support localization?​

You can write descriptions in your API Spec in the local language of your choice and we will be able to pick that up and display it in the portal. Our CodeGen engine however will output its default content in English. Anything that you can write as input can be in any language and the portal will be able to handle it.

How does APIMatic differ from Stoplight, Redoc or Swagger?​

The ability to have SDKs and idiomatic code samples that work with SDKs. All the other products are generating wrappers around the curl commands to give out language-specific snippets.

Changes made to the portal are reflected in the Preview section but not on the published portal​

If you are trying to make changes to an already published portal, then you will have to re-publish the portal to reflect these changes.

Troubleshooting​

Make sure to check the spam/junk folder in case the activation email is filtered out from your inbox. If that does not work, reach out to APIMatic support so they can help you with the final step of the activation.

I have accepted the team invitation but I am still unable to see any of my team member’s API.​

The API owners within your team will be required to explicitly share their APIs with you in order for you to get access to their APIs in your APIMatic dashboard.

My HTML-based tables are showing up fine in the markdown WYSIWYG editor in my custom guides but when I generate the documentation portal, the tables get jumbled up.​

APIMatic custom guides support a subset of GitHub flavored markdown. Even though the WYSIWYG editor shows the HTML tables correctly, the HTML tables will not get rendered correctly in the portal. You can swap them with markdown tables and that will work for you.

My API docs portal is throwing a 500 error. How can I fix this issue?​

Something within the API specification file is causing the portal generation to fail. Reach out to APIMatic Support and they will debug the issue for you.

I keep getting “There is a problem loading the documentation” when I try to open my API portal.​

In most cases, an expired account subscription or invalid API specification causes the portal to display this error. Reach out to your APIMatic account executive or APIMatic support to have this issue resolved.

The “Try it out” feature in my portal does not work even though the curl command generated in the code sample works fine, what should I do?​

Chances are, your API server does not allow Cross-Origin Resource Sharing and this is causing the API calls to fail. You can either enable CORS on your API server, or you can enable APIMatic’s proxy feature to fix this issue.

Why are the optional parameters of an endpoint not showing up by default in the code samples generated within the API explorer?​

The optional parameters will not show up in the generated code samples unless valid object-level examples have been provided for them in the spec file. You can also turn on our codegen setting GenerateExamplesForOptionalFields to display optional parameters in the code samples.

Why is APIMatic changing the order of the parameters for some of my endpoints?​

APIMatic by default follows the parameter order that is defined in the API specification file with the exception that all required parameters should be displayed before the optional parameters. In the case where your spec defines optional parameters above required parameters, we will re-order the parameters so that all required parameters are displayed at the top. This is done to facilitate the SDK generation process.