You can curate your collection’s overview to introduce your public APIs to your API consumers. A well-curated collection invites your API consumers to fork and use your APIs—and gets them to their first 200 OK response in the fewest steps possible.
Open your collection’s Overview tab, click the collection’s name, and rename your collection.
To learn more, see Configure a collection.
Name your collection something that communicates its purpose. For example, if you’re renaming your API reference collection, choose a name that communicates it’s the API reference for the public APIs in your workspace. If you’re renaming your overview collection, choose a name that communicates it’s the starting point for the public APIs in your workspace.
Use the following guidance to choose a name:
Use keywords that speak to your target audience. Choose words and phrases that your API consumers may search for, such as those that relate to what your API does, specific use cases, and common industry terms. For example, instead of “Data API”, name your collection “Financial Market Data API” or “Get started with the Financial Market Data API”.
Choose a descriptive yet concise name. Convey what your API does in the fewest words possible. Use action-oriented language and avoid vague terms. For example, instead of “User API”, name your collection “Create customer accounts API”.
Be consistent across your workspace and collections. Consistency improves your API consumer’s ability to scan and navigate your workspace and collections. For example, if you name a collection “Financial Market Data API”, name a similar collection “Financial Market News API” (and not “APIs for finance news”).
Tip: Use 🤩 emojis to make your collection name stand out.
Open your collection’s Overview tab, click the collection’s description, and write a new description.
To learn more, see Configure a collection.
Write a description that gets your API consumers to their first API request and 200 OK response in the fewest steps possible. Use the following guidance to write a description:
Introduce your APIs and the services they offer. Give your API consumers an overview of your APIs. You can add screenshots, videos, and links. List your APIs, highlight their value, explain what each does, and define any key concepts your API consumers need to understand. Help your users navigate your collection with a table of contents that links to folders and requests within your collection.
Get your API consumers started. Focus on the steps each API consumer must complete to get their first 200 OK response, and document these steps for them. For example, if they must sign up for an account, give them a link to where they can sign up. If you host “Get started” documentation elsewhere, link to it.
Explain authentication and authorization. Often, authentication and authorization introduce the most friction between your API consumers and your APIs. Outline the steps someone must complete to make their first successful API call.
Link to further documentation, such as tutorials. If you have integration guides and tutorials, link to them to let your users know what to do once they get their first 200 OK response.
Link to help and the community. Add links to your support channels, forums, and community resources. This ensures your API consumers know where to go when something goes wrong.