1. Home
2. Solutions
3. Tutorials

When your organization maintains multiple APIs across different teams, it's easy to lose track of what exists, who owns what, and how services depend on each other. New team members struggle to find documentation. Teams accidentally build duplicate functionality because they don't know an API already exists. Dependencies are unclear until something breaks.

Fastly's API Inventory feature lets you transform raw traffic data into an organized, documented reference that your entire organization can use. In this tutorial, you'll curate discovered APIs into a living catalog with clear descriptions and team ownership, creating a single source of truth for understanding your API landscape.

By the end of this tutorial, you'll have a documented team API reference that helps teams understand what APIs exist, who owns them, and how they're used across your organization—making onboarding easier, preventing duplicate work, and clarifying dependencies.

Prerequisites: API Discovery enabled on your account with some traffic collected.

Instructions

Building an effective Team API reference from Discovery data is like managing visitor access to a building. Discovery observes foot traffic—people who walk through the doors—but doesn't tell you who they are, why they're there, or whether they're supposed to be there. Inventory, by comparison, lets you decide which visitors to document, add context about their purpose and authorization, and maintain an organized record that your security team can reference to grant appropriate access, investigate suspicious activity, or understand who should be in the building at any given time.

In practice, this means following a three-stage workflow: observation, curation, and documentation. API Discovery continuously observes API traffic flowing through Fastly's Edge network, capturing domains, paths, and HTTP methods and filtering out the noise. This gives you complete visibility, but without context, it's just a list of URLs. The Inventory feature lets you curate this data by saving the APIs that matter to your organization and, like Discovery, your inventory continues to update as traffic patterns change. Finally, you add the context that transforms a saved list into a useful reference: tags for organization and filtering, descriptions that explain what each API does, team ownership assignments, and notes about dependencies or technical details.

What makes a good Team API reference? It should be organized so teams can quickly find what they need, whether they're searching by domain, function, or team ownership. It should be documented with clear descriptions that help developers understand an API's purpose without diving into code. It should establish ownership so everyone knows who to contact about a particular API. And it should be maintained as a living document that evolves as your API landscape changes.

Some things we want from an effective Team API reference are:

• Quick discoverability—teams can find APIs by searching for domains, paths, functions, or owners
• Clear documentation—descriptions explain what each API does without requiring code inspection
• Flexible organization—tags allow grouping APIs by function, service, team ownership, status, or any criteria that suits your organization
• Easy maintenance—updates to descriptions and tags keep the reference current as your API landscape evolves

Let's get started.

Review your discovered APIs

Start by reviewing the list of discovered APIs being called through your service. You'll likely recognize some APIs immediately. These are the ones you and your team use regularly. Others might be unfamiliar, and that's expected. For example, you might recognize your team's authentication endpoints right away, but see several payment-related APIs that you know belong to a different team. Your goal is to get a sense of what's being called so you can decide what to include in your reference.

1. Log in to the Fastly control panel.
2. Navigate to Security > API Discovery.
3. Click the Discovery tab.
4. From the services menu, select the appropriate service. A list of discovered APIs appears for that service.
5. Review the list of discovered APIs. These are all the APIs actively being called through your service.

Establish a tagging strategy

Before you start building your Team API Reference, establish a tagging strategy that will help you organize and filter your inventory effectively. Tags are labels you can apply to APIs to group them by team ownership, functional area, status, or any criteria that suits your organization. Each tag can have a description that explains its purpose, making it easy for others to understand your organizational scheme.

Consider the kinds of categories that will be most useful for your team. Common tagging approaches include:

• Team ownership - Tag APIs by the team responsible for them (e.g., "Platform Team", "Payments Team", "Mobile Team")
• Functional area - Group APIs by what they do (e.g., "Authentication", "Billing", "User Management")
• Status - Track API lifecycle stages (e.g., "Production", "Deprecated", "Beta")
• Action items - Flag APIs that need attention (e.g., "Needs Review", "Incomplete Documentation")

You can mix and match these approaches. For example, an API might be tagged with both "Platform Team" and "Authentication" to indicate both ownership and function.

To create a tag:

1. Click the Tags tab.
2. Click Create tag.
3. In the Name field, enter a tag name. For example, if you plan to tag all the APIs owned by your team, you might use Platform Engineering.
4. In the Description field, enter a description of what this tag means and when to use it. For example, APIs owned and maintained by the Platform Engineering team.
5. Click Create.

Then, repeat this process for each tag you plan to use. You can always create additional tags later as your needs evolve, but starting with a core set helps maintain consistency as you document your APIs.

Add APIs to your inventory

Once you've created tags to help you organize your inventory, start building that inventory by adding APIs to your reference catalog. Start with the APIs you know well, the ones you and your team use regularly. For unfamiliar APIs, look at the domain patterns and URL paths to identify which teams likely own them. For example, you might immediately add your team's authentication and user profile APIs, then notice several /api/payments/* endpoints and add those knowing they belong to the payments team. You don't need to add everything at once; focus on the APIs that matter most to your organization.

1. Click the Discovery tab.
2. Click Quick add for each API you want to save to your inventory. You can click again to deselect any API.
3. Repeat as necessary for each discovered API.
4. Once you've selected all the APIs you want to inventory, click Refresh. The APIs are removed from your list of discovered APIs and saved to your inventory.

Document your APIs

Once you've got a tagging strategy in place, start adding. Start with what you know. Even incomplete information is useful and you can always refine it later. For example, for your authentication API, you might write "Validates user credentials and issues JWT tokens" and tag it with "Platform Team" and "Authentication." For APIs where you're unsure of the purpose, add a basic description and tag them for follow-up with the responsible team.

1. Navigate to Security > API Discovery.
2. Click the Inventory tab.
3. Click View next to the API that needs documenting. The Operation details page appears.
4. Click Edit operation.
5. In the Description field, enter an explanation of what the API does. For example, Retrieves product catalog with pricing and availability or Creates new user accounts with email verification.
6. From the Tag field, select or enter the appropriate tag (e.g., Platform Team). You can also click Create new tag if a tag you need doesn't exist yet.
7. Click Save. The API appears in Inventory.

You'll repeat this process for each API in your inventory. Don't worry if you don't have complete information for every API. Add what you know now and update entries as part of maintaining your Inventory as you learn more. Tagging APIs with "needs-review" or the responsible team's name can help you track what needs follow-up.

Maintain and update your inventory

Your API reference isn't static, it evolves as your API landscape changes. Make it a habit to review your inventory regularly, at least monthly or quarterly depending on how quickly your APIs change. During a review, check API Discovery for newly deployed APIs to add, look at your service's Event log to see recent inventory changes, and assess whether existing descriptions and tags are still accurate. As you review, you'll identify APIs that need updates: descriptions to refine when you learn new information, deprecated tags to add when teams retire endpoints, or entries to remove for APIs that are no longer being used.

Update an existing API in inventory

When you learn new information about an API, such as learning it's been deprecated, update its inventoried information to keep your reference current.

1. Navigate to Security > API Discovery.
2. Click the Inventory tab.
3. Click the View operation icon next to the API that needs updating. The Operation details page appears.
4. Click Edit operation.
5. Update the Description to reflect the new information. For example, you might change Handles user authentication to Handles user authentication (DEPRECATED - use v2 endpoint instead) to signal an API has been deprecated.
6. Add or update Tags to reflect the status. For example, add a "deprecated" tag.
7. Click Save.

Remove an API from inventory

If an API hasn't received traffic in a while and you've confirmed it's no longer needed, you can remove it from your inventory to keep your reference clean and focused.

1. Navigate to Security > API Discovery.
2. Click the Inventory tab.
3. Click on the API you want to remove.
4. Click Delete or Remove from Inventory.
5. Confirm the deletion.

Share your API reference

Once you've built and documented your inventory, you can share it with your team and organization in two ways. If your colleagues can access the Fastly control panel, point them to Security > API Inventory where they can view and search the reference. This works well for team members who need to reference it regularly. For those without access, export the inventory as a CSV file to share the documentation you've created.

To export your API reference for teams without control panel access, or to import it into other documentation tools:

1. Navigate to Security > API Discovery.
2. Click the Inventory tab.
3. Click Export to download your inventoried APIs as a CSV file.

The exported CSV includes all APIs in your inventory along with all the context you've added: domains, paths, methods, descriptions, tags, and notes. You can share this with your manager for reporting, with new team members for onboarding, or with other teams who need to understand which APIs are available for their projects.

You now have a living API reference that documents your organization's API landscape. New team members can use this to understand what APIs exist and who to contact about them. Teams can reference it to avoid building duplicate functionality. And you have an easy way to answer questions like "Which API should we use for this new feature?" or "What have we been working on this quarter?".

What's next

• Continue monitoring the discovered APIs to catch new APIs as they're being called through your service.
• Review your inventory regularly to keep your documentation current.
• Regularly review your service's Event log to track API Inventory changes.