The goal of the Docs section of an API Portal is to provide clear, concise, and accessible documentation that helps developers understand how to use your API. The content should cater to beginners and experienced developers, providing information from getting started to in-depth technical details.
Apiable provides a template to help get you started but expects you to customize it to the needs of your API Consumers.
Typically, the Docs section should include some or all of the following:
Overview
Introduction to the API
Key features
Use cases
Getting Started Guide
Authentication methods
Quickstart with sample code
Environment setup
Endpoints and Methods
Endpoint structure (e.g., REST, GraphQL)
HTTP methods (GET, POST, etc.)
Parameters (query, path, body)
Response formats and data types
Error codes and troubleshooting
Examples and Use Cases
Code examples in different languages
Common use cases
Postman collections
Rate Limits and Quotas
Usage limits
Throttling behavior
Versioning and Deprecation Policy
API versioning
Deprecation Schedule
Security and Best Practices
Security guidelines
Best practices for efficient API use
SDKs and Libraries
Official SDKs
Recommended third-party libraries
FAQs and Troubleshooting
Common issues and fixes
Frequently asked questions
Changelog
Release notes
Upcoming features
Support and Contact
Support channels
Community resources
Where to find the documentation on your portal
Navigate to your Portal and either:
Append: /docs/start to the URL; or
Click on the docs link in the header navigation.
Example Docs page.
How to modify and add to your documentation
In the administration dashboard, Navigate to Content > Documentation
Here, you will find the documentation editor tool.:
Creating a New Page
Documentation can contain multiple pages. To create a new page:
Click on the + Add new page button at the bottom of the navigator.
Name your new page (e.g., "API Overview," "Authentication Guide").
Expand the right chevron (>) to show more options.
Click on + Add section to create a new section on this page.
Once done, click Save Changes.
Creating a New Section
Categories help structure your API documentation. To add a new section to an existing page:
In the left sidebar, click on the Add Section button.
A new section will appear (in green) where you can enter a name for the new category (e.g., "Introduction" or "Advanced Topics").
A slug (url) will be given for you. You may override this to make it more readable.
Click Save to create the category. It will now appear (black) in the sidebar.
Modifying an Existing Section
To edit an existing section:
Select the page containing the section you want to modify.
Click on the section you want to edit. The section content will appear in the editor.
Make the necessary changes (e.g., update text, fix errors, add new examples).
Once you're finished, click Save Changes.
Showing Changes
The Show changes icon is at the top right of the page. Clicking on it will show changes that have not yet been persisted.
Green - New changes
Red - Overrides previous text.
Black - No changes.
Rearranging Pages and Categories
Rearrange Sections: You can move sections between pages or change their order within a page by dragging and dropping the section titles in the sidebar.
Rearrange Categories: Similarly, you can rearrange pages by dragging them to the desired position in the sidebar.
Deleting a Page or Section
To delete a section, hover over the page in the sidebar and click the delete icon (a trash can symbol).
To delete an entire page, hover over the page title and click the delete icon. Be cautious, as this will remove all sections within that page.
Additional Features
Previewing Changes
As you edit pages, you can preview your changes in real-time. The documentation editor provides a preview mode that shows how your changes will look on the live API Portal.
Customizing the Portal Appearance
The dashboard also allows you to customize the appearance of your documentation portal. You can:
Change theme colors.
Adjust the style of buttons, modals, and other UI elements to match your brand.
Change the code sample colors.
To customize your portal, navigate to Portal > Theme
More information can be found on Changing your portal look and feel.
Best Practices
Organize by Topic: Group related pages together into categories that make sense (e.g., Authentication, Data Endpoints, FAQs).
Use Clear Titles: Ensure each page and category has a descriptive title so that users can easily find what they need.
Include Code Examples: If possible, provide code snippets in multiple languages to help developers understand how to use your API.
Regularly Update Content: Keep your documentation up-to-date with new features, fixes, and improvements.