Getting started with API documentation

Plans supporting API documentation

The API documentation feature in Document360 provides a complete solution for creating and managing API references. This feature allows you to generate high-quality API documentation that helps users understand and work with your APIs effectively. You can generate this documentation by uploading the API specification file from a URL, a JSON/YAML/YML file, or by integrating with a CI/CD flow.

Additionally, the Try it! feature in Document360 allows you to test API endpoints directly on the Knowledge base site. The interactive console in the Knowledge base site allows developers to input the necessary parameters and execute API calls, getting real-time responses. This feature is useful for troubleshooting and understanding how an API behaves without leaving the documentation or writing any code.

API documentation onboarding

When signing up for Document360, users choose their primary use case in Step 1 of the onboarding flow. For users who wish to create API documentation, Document360 provides a streamlined onboarding experience. If you select API documentation as your use case, you will be redirected to the API setup flow, where you can create API references using the available options.

In Step 2 of the onboarding flow, you will have three options for creating an API reference:

• Upload API file: Supports JSON/YAML/YML files (OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1, and Postman collections).

• Create from URL: Automatically fetches the API specification from the hosted URL.

• Try sample pet store API file: If you don't have an API file ready, you can use the sample file (Pet store API) offered by Document360 to populate your workspace.

Uploading an API definition file

To create an API reference from an API definition file, select the Upload API file radio button. Next, click Upload from my device or drag and drop your API specification file from your device.

NOTE

The file formats supported for the API definition file are JSON, YAML or YML.

The system will parse the file and generate the API reference automatically.

• If any alerts/warnings are detected in the uploaded file, a high-level overview will be displayed during onboarding. You can view in-depth details in the knowledge base portal in the logs section under More options within API references.

• If any error is detected in the uploaded file (for example - Unsupported file format), replace the uploaded file with an alternate file.

Entering an API documentation URL

To create an API reference from an API documentation URL, select the Create from URL radio button. Next, enter the URL for your OpenAPI file in the URL to your API definition field. Document360 will fetch and process the API structure. Similar to file uploads,

• If any alerts/warnings are detected, you can view them in the knowledge base portal in the logs section under More options within API references.

• If any error is detected (for example - Invalid URL), enter the valid URL for your OpenAPI file.

Skipping API setup

If you choose the Try sample pet store API file option,

• Document360 will automatically create a sample API reference (Pet store API).

• This will be available in draft mode. You can review the endpoints before publishing or upload your spec file and publish it later.

Personalize your knowledge base

In Step 3, you can enter your preferred website URL. If you want to skip this step, the domain will default to the one linked to your registration email.

Brand guidelines

In Step 4, your project name, default language, branding logo, and brand colors are automatically set based on your provided URL. However, you can edit these fields if needed. Your browser’s language settings determine the default language. English will be selected by default if other languages don’t support your browser’s language.

NOTE

• If you choose Spanish or Brazilian Portuguese as your default language, the portal language will be set to Spanish or Brazilian Portuguese. Otherwise, English will be the default language.

• The branding logo and primary/secondary colors are extracted from your website. If you choose to Skip this step, the project name will be derived from your registration email, and Document360’s default logo and colors will be applied.

Set documentation privacy

In Step 5, you can choose the desired privacy settings for your site:

• Private: Restrict access to the Knowledge base so that only team accounts can view and interact with the content, keeping it secure and internal.

• Public: Make the Knowledge base accessible to everyone, including external users, allowing open access to all content.

• Mixed: Combine private and public access by allowing some sections of the Knowledge base to be visible to the public while keeping other sections restricted to team accounts only.

Finally, click Next to complete your API onboarding flow.

You will be redirected to the API documentation workspace, where:

• You will see the API reference of the API specification you provided during onboarding.

• If you did not provide an API specification, a sample API reference (Pet store API) will be available in draft mode.  

Authorization techniques

When interacting with an API, it is important to ensure that only authorized users can access certain data or perform specific actions. This is done using authorization techniques, which control access and permissions. Document360 supports various methods of authorization to secure your API, including:

• Basic authentication: Requires a username and password passed in the request.

• Bearer token: Authenticates with a token generated after login.

• API key: Uses a unique key, passed in the request headers, for authentication.

• OAuth2: Secures APIs through various flows, such as Authorization code, PKCE, Client credentials and Implicit flows.

• OpenID Connect: Extends OAuth2 by adding user identity verification.

Authorization considerations (OAuth2 and OpenID)

When working with APIs that use OAuth2 or OpenID for authorization, certain settings are essential for proper functionality.

• Redirect URI: This is the URL that the user will be redirected to after completing an authorization flow. Ensure you set the URI in the format: domain/oauth. For example: https://apidocs.document360.com/oauth.

• Silent renewal: Silent renewal automatically refreshes the authorization token in the background, so users don’t have to reauthenticate during their session. This keeps their session active without interruption. To prevent authorization from expiring during sessions where users interact with the Try It! feature, Document360 automatically renews the refresh token in the background. This ensures that users won’t need to reauthenticate manually.

Purchasing

You will have access to 1 API workspace as part of all Document360 paid plans (Professional, Business, and Enterprise). If you wish to purchase additional API workspaces,

1. Navigate to Settings() > Knowledge base portal > Billing > My plan.

2. Click Purchase add-on.

3. Add the desired number of API documentation workspaces. Review the cost of the add-on and the amount due.

4. Click Confirm payment to proceed with the payment.

Troubleshooting

API access issues

Error: 400 error – API access is disabled. Please contact your project administrator.

This error occurs when the public API access is deactivated in the project settings.

Steps to resolve:

1. Navigate to Settings() > AI features > Eddy AI in the Knowledge base portal.

2. Under the AI search suite section, ensure that the Public API checkbox is selected.

   

3. If the issue persists after following these steps, please contact the Document360 support team for further assistance: Contact Document360 Support

Related videos

Experience our modern API Documentation in Document360 like never before

Test API endpoints directly from Documentation with Try it feature

Additional information

Introducing API Documentation: Enhance your API Experience - Click to read