--- title: "RFC 9727 api-catalog Explained" description: "RFC 9727 standardizes API catalogs, enhancing discoverability, governance, and lifecycle management for improved API operations." canonicalUrl: "https://zuplo.com/learning-center/rfc-9727-api-catalog-explained" pageType: "learning-center" authors: "adrian" tags: "API Security" image: "https://zuplo.com/og?text=RFC%209727%20api-catalog%20Explained" --- [RFC 9727](https://datatracker.ietf.org/doc/rfc9727/) introduces a standardized way for organizations to share API information through a well-known URI, `/.well-known/api-catalog`. Released in June 2025, this standard simplifies [API discovery](./2025-07-31-api-discoverability-why-its-important-the-risk-of-shadow-and-zombie-apis.md), governance, and lifecycle management by requiring a machine-readable catalog in the Linkset format (`application/linkset+json`). The catalog includes API endpoints, version details, policies, and links to [OpenAPI](https://www.openapis.org/) specifications, ensuring consistent and secure API documentation. ### Key Highlights: - **Location**: API catalogs are hosted at `/.well-known/api-catalog`, accessible via HTTPS. - **Format**: Uses the Linkset format with a profile parameter (`https://www.rfc-editor.org/info/rfc9727`) to ensure compliance. - **Purpose**: Improves API discoverability, reduces outdated APIs, and strengthens governance. - **Security**: Requires HTTPS, TLS encryption, and read-only access for external users. RFC 9727 addresses challenges like API sprawl and poor documentation, making it easier for developers to locate, understand, and use APIs while helping organizations maintain consistency and security in their API portfolios. ## RFC 9727 Technical Requirements and Structure ### Well-Known URI and Linkset Format Requirements RFC 9727 lays out the technical groundwork for implementing API catalogs. Specifically, it mandates that HTTPS HEAD requests to `/.well-known/api-catalog` must return a Link header containing the RFC-defined relations. This ensures compatibility with various discovery tools and methods. To protect the integrity of API discovery, the catalog must be accessible exclusively over HTTPS, utilizing TLS for secure communication. The API catalog itself must be published in the Linkset format, using the `application/linkset+json` content type. Additionally, it must include a profile parameter with the URI `https://www.rfc-editor.org/info/rfc9727` to clearly denote compliance with RFC 9727. Kevin Smith of [Vodafone](https://www.vodafone.com/) finalized RFC 9727 in June 2025 after 13 revisions spanning two years. He described its purpose succinctly: > A request to the api-catalog resource will return a document detailing the > Publisher's APIs. These technical requirements are designed to enhance API discoverability and ensure consistent catalog management. ### API Catalog Content and Metadata Beyond the technical setup, the catalog's content is key to improving API discoverability. An RFC 9727-compliant API catalog must provide hyperlinks to API endpoints, allowing automated tools to reliably locate and interact with the APIs. To elevate the catalog from a simple endpoint list to a developer-friendly resource, it should include detailed metadata. This can cover usage policies, API version details, and links to [OpenAPI Specification (OAS) definitions](./2024-09-25-mastering-api-definitions.md). If embedding this metadata directly in the catalog isn’t feasible, it should instead be accessible at the corresponding API endpoint URIs. This approach gives publishers the flexibility to either centralize the information in the catalog or distribute it across individual endpoints. The catalog can also use the "item" link relation to identify resources that represent individual APIs. Additionally, RFC 9727 supports catalog federation via the "api-catalog" relation type. This feature enables linking to other API catalogs, paving the way for distributed networks of catalogs while maintaining discoverability. ### api-catalog Examples Here are some examples, pulled straight from the RFC #### Using Linkset with Link Relations This example uses the Linkset format (RFC9264) and the following link relations defined in (RFC8631): - `service-desc`: Used to link to a description of the API that is primarily intended for machine consumption (for example, the OpenAPI specification, YAML, or JSON file) - `service-doc`: Used to link to API documentation that is primarily intended for human consumption. - `service-meta`: Used to link to additional metadata about the API and is primarily intended for machine consumption. - `status`: Used to link to the API status (e.g., API "health" indication) for machine and/or human consumption. Client request: ```http GET .well-known/api-catalog HTTP/1.1 Host: example.com Accept: application/linkset+json ``` Server response: ```http HTTP/1.1 200 OK Date: Mon, 01 Jun 2023 00:00:01 GMT Server: Apache-Coyote/1.1 Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727" ``` ```json { "linkset": [ { "anchor": "https://developer.example.com/apis/foo_api", "service-desc": [ { "href": "https://developer.example.com/apis/foo_api/spec", "type": "application/yaml" } ], "status": [ { "href": "https://developer.example.com/apis/foo_api/status", "type": "application/json" } ], "service-doc": [ { "href": "https://developer.example.com/apis/foo_api/doc", "type": "text/html" } ], "service-meta": [ { "href": "https://developer.example.com/apis/foo_api/policies", "type": "text/xml" } ] }, { "anchor": "https://apis.example.net/apis/cantona_api", "service-desc": [ { "href": "https://apis.example.net/apis/cantona_api/spec", "type": "text/n3" } ], "service-doc": [ { "href": "https://apis.example.net/apis/cantona_api/doc", "type": "text/html" } ] } ] } ``` #### Using Linkset with Bookmarks You could also just embed a URL within the `item` property instead: ```json { "linkset": [ { "anchor": "https://www.example.com/.well-known/api-catalog", "item": [ { "href": "https://developer.example.com/apis/foo_api" }, { "href": "https://developer.example.com/apis/bar_api" }, { "href": "https://developer.example.com/apis/cantona_api" } ] } ] } ``` #### Nesting API Catalog links If your catalog is large, and cleanly segmented, you can consider having a primary catalog which branches out into sub-catalogs (ex. different products). ```json { "linkset": [ { "anchor": "https://www.example.com/.well-known/api-catalog", "api-catalog": [ { "href": "https://apis.example.com/iot/api-catalog" }, { "href": "https://ecommerce.example.com/api-catalog" }, { "href": "https://developer.example.com/gaming/api-catalog" } ] } ] } ``` ### Security Requirements and Best Practices With the catalog’s structure and content defined, ensuring secure and reliable access becomes a top priority. RFC 9727 emphasizes operational responsibility and data protection as critical components of API catalog management. Publishers are encouraged to adhere to best practices, such as monitoring the catalog’s availability, performance, and metadata accuracy. To maintain quality, both manual reviews and automated checks should be conducted regularly. These efforts help identify and fix syntax errors, preventing disruptions in automated discovery processes. Lifecycle management is also a central focus. Removing outdated or deprecated API entries as part of the release cycle reduces risks tied to insecure or obsolete API versions. By prioritizing these security measures, publishers can ensure their API catalogs remain reliable and effective for discovery. ## How RFC 9727 Changes API Catalog Management RFC 9727 introduces a transformative approach to managing API catalogs. It modernizes API discovery while integrating governance and lifecycle management into a unified framework. By providing standardized discovery tools and governance structures, this specification turns API catalogs from static, hard-to-navigate repositories into dynamic, machine-readable resources that actively support API operations. ### Improved API Discovery RFC 9727 makes API discovery faster and more reliable. By standardizing the Linkset format, it ensures that discovery tools can interpret catalog information consistently, no matter who publishes it. This eliminates the previous chaos where organizations used different formats and scattered their catalogs across various locations. For developers, this means easier access to API details without the need for extra manual work. Publishers also gain new flexibility. They can announce APIs through multiple channels, making APIs more visible at key points in a developer's workflow - whether browsing documentation or sending programmatic requests. The inclusion of metadata is another game-changer. Catalogs can now provide critical details like version histories, usage policies, and links to OpenAPI specifications. This gives developers immediate access to the information they need to evaluate and integrate APIs effectively. All of this creates a seamless discovery process, laying the groundwork for improved governance and lifecycle management. ### Better API Governance Beyond discovery, RFC 9727 strengthens [API governance](./2025-07-14-what-is-api-governance-and-why-is-it-important.md). The requirement for a well-known URI ensures that every API domain publishes its catalog in a consistent, predictable location. This fixed setup, combined with enforced metadata standards, allows governance teams to monitor API usage more effectively and ensure compliance. This centralized system also minimizes risks, such as developers accidentally violating usage policies or working with outdated API versions. By clearly communicating policies and guidelines, organizations reduce confusion and errors. RFC 9727 also encourages best practices, like regularly monitoring catalog availability and conducting security reviews before deployment. These steps help maintain high-quality catalogs that accurately reflect an organization’s API offerings. To safeguard catalog integrity, publishers are advised to enforce read-only access for external requests to the well-known URI. This ensures that while APIs remain discoverable, their catalogs are protected from unauthorized modifications. ### API Lifecycle Management Benefits RFC 9727 simplifies API lifecycle management by embedding catalog updates into release workflows. It suggests that API management tools include catalog maintenance as a standard part of their processes, ensuring catalogs always align with the latest API deployments. The specification also aids in handling legacy APIs and deprecated endpoints. By allowing publishers to include metadata about older versions, it provides developers with clear migration paths to newer services. Catalogs can communicate deprecation timelines, redirect users to updated versions, and outline usage policies to guide transitions. This transparency reduces the usual headaches associated with API version changes. Additionally, RFC 9727 tackles the issue of ["zombie APIs"](./2025-07-31-api-discoverability-why-its-important-the-risk-of-shadow-and-zombie-apis.md) - outdated APIs that linger and pose security risks. By requiring publishers to remove obsolete entries during the release cycle, the specification helps maintain clean and secure API inventories. Routine catalog audits become an essential part of this process. Framework providers can take this a step further by automating lifecycle management. For example, any changes to API links or metadata can trigger automatic catalog updates, keeping discovery information accurate in real time. By aligning catalog updates with API release schedules, organizations can maintain a precise and up-to-date inventory, reflecting the dynamic nature of modern API ecosystems. ## Implementing RFC 9727 with Zuplo Zuplo’s built-in [OpenAPI integration](https://zuplo.com/blog/2023/03/06/announcing-open-api-native-support) ensures your API catalog stays in line with RFC 9727 without extra effort. This real-time synchronization prevents the common issue of outdated API catalogs when changes occur, as the developer portal automatically reflects updates. ### Setting Up RFC 9727 Compliance in Zuplo With Zuplo’s programmable features, you can create an RFC 9727-compliant API catalog at `/.well-known/api-catalog` in Linkset format. Start by developing a custom handler that pulls information from your OpenAPI specifications and formats it to meet RFC 9727 requirements, including details like API versions, usage policies, and links to documentation. To make your APIs more accessible, configure your developer portal to expose the `api-catalog` endpoint. This ensures discoverability for both developers and automated tools. Zuplo’s flexibility allows you to fully customize the catalog generation process to align with your specific RFC 9727 needs. ### Zuplo Features for RFC 9727 Support Zuplo comes packed with features that assist in meeting RFC 9727 requirements. **GitOps integration** ensures your API catalog stays consistent and up-to-date. Any changes made to API specifications through Git workflows automatically sync with the catalog. Zuplo’s **API governance tools** - like API linting, pull requests, and CI workflows - help maintain catalog quality. These tools align with RFC 9727’s recommendation for both human and automated syntax validations. Together, these features simplify compliance and make ongoing catalog management easier. ### Maintaining Accurate and Secure Catalogs Zuplo’s automation and GitOps workflows ensure your catalog remains accurate and secure throughout its lifecycle. For example, when APIs are deprecated or removed during your release process, the catalog can be updated automatically, addressing RFC 9727’s requirement to remove outdated entries. Syntax validation is another key area. By integrating automated checks into your CI/CD pipeline, you can catch errors in OpenAPI specifications before they impact production. Since Zuplo natively supports OpenAPI, syntax issues are flagged during the build process, ensuring your catalog remains valid. ## Tools and Strategies for RFC 9727 Implementation To successfully implement an RFC 9727-compliant API catalog, you’ll need a combination of effective tools and thoughtful strategies. This standard emphasizes both technical precision and operational reliability, so it’s crucial to establish processes that ensure compliance from the outset. ### Tools for RFC 9727 Implementation **JSON schema validators** play a key role in ensuring your API catalog meets the required structure and format. These tools, like [AJV](https://ajv.js.org/), catch syntax errors early, preventing issues that could disrupt API discovery. By integrating JSON schema validation into your build process, you can verify catalog compliance before deployment. **Linkset format checkers** are specifically designed to validate the `application/linkset+json` format. They ensure that the catalog correctly implements linkset structures, including relation types, target URIs, and metadata. The [Internet Engineering Task Force](https://www.ietf.org/) (IETF) provides reference implementations that can serve as benchmarks. **OpenAPI linting tools** help maintain consistency between API specifications and their catalog entries. Tools such as [RateMyOpenAPI](https://ratemyopenapi.com) allow you to enforce custom rules, ensuring every API in the catalog is properly documented and versioned. **CI/CD integration plugins** streamline compliance checks throughout your development workflow. Plugins for platforms like [GitHub Actions](https://docs.github.com/actions), [GitLab CI](https://about.gitlab.com/solutions/continuous-integration/), and [Jenkins](https://www.jenkins.io/) can automate validation tests, generate reports, and even block deployments if compliance issues are detected. Once these tools are in place, the next step is to develop strategies to maintain and monitor your API catalog over time. ### API Catalog Maintenance Strategies **Automated catalog generation** simplifies updates by linking catalog creation directly to your OpenAPI specifications. This ensures that your catalog stays current as your APIs evolve. Pair this with **version control integration** to treat your catalog like code - track changes, review updates, and roll back problematic modifications through Git workflows. **Release lifecycle integration** keeps your catalog accurate by embedding updates into your API deployment process. For example, removing outdated API entries during the release lifecycle helps maintain a clean and reliable catalog. **Security maintenance** is another critical aspect. Regularly update access controls, review authentication policies, and monitor for unauthorized access attempts. RFC 9727 requires enforcing read-only privileges for external requests and internal monitoring systems, while limiting write access to designated roles. Conducting regular security audits ensures these controls remain effective. By combining these strategies with ongoing monitoring, you can ensure your catalog remains compliant and efficient. ### Tracking API Catalog Usage and Performance Tracking usage and performance metrics is essential for understanding how developers interact with your catalog. Analyze requests to the `/.well-known/api-catalog` URI and correlate them with subsequent API requests to measure engagement. This data can reveal how effectively your catalog supports API discovery. **Performance monitoring** is vital for maintaining a responsive and reliable catalog. Key metrics to track include response times, error rates, and overall availability. These factors directly affect the experience of developers and automated tools. **Analytics integration** with platforms like Zuplo provides deeper insights into usage patterns. You can identify which APIs are most accessed, when peak discovery times occur, and how different developer groups interact with your catalog. These insights can guide API improvements and better catalog organization. **Rate limiting analysis** helps balance accessibility with system protection. RFC 9727 recommends implementing rate-limiting measures to prevent abuse and mitigate denial-of-service attacks. Regular analysis ensures these limits are effective without hindering legitimate users. **Compliance monitoring** involves scanning for issues such as missing metadata, broken links, or formatting errors. Keeping an eye on these details ensures your catalog maintains high quality as your API offerings grow. RFC 9727 also emphasizes the importance of monitoring availability, performance, usage, and metadata accuracy to maintain operational excellence. ## Conclusion and Key Takeaways RFC 9727 marks an important step in API standardization, offering a framework for API discovery through a well-known URI approach. By introducing a structured method for API catalogs, RFC 9727 makes programmatic discovery possible - a critical feature for businesses that rely heavily on APIs. This capability helps organizations address the ongoing challenge of "zombie" APIs - outdated or neglected endpoints that can create significant security vulnerabilities. The standard fosters better collaboration, consistent API management, and scalable governance while reducing risks associated with obsolete endpoints. It also supports the growth of API portfolios by providing a systematic approach to their management, ensuring consistency and improving security through integrated lifecycle governance. To make adopting RFC 9727 easier, **Zuplo streamlines implementation** with features like native OpenAPI integration. This ensures that gateway configurations and specifications remain synchronized, removing the manual effort of maintaining accurate API catalogs. As Tom Carden from [Rewiring America](https://www.rewiringamerica.org/about-us) shared: > "Zuplo is the ultimate one-stop shop for all your API needs. With rate > limiting, [API key management](https://zuplo.com/features/api-key-management), > and documentation hosting, it saved us weeks of engineering time and let us > focus on solving problems unique to our mission." Zuplo equips organizations with tools to customize compliance, enhance security, and simplify operations with features like OpenAPI synchronization, advanced authentication options, and detailed analytics. These capabilities address the complexities that often hinder successful adoption of standards like RFC 9727. As API ecosystems grow, RFC 9727 lays the groundwork for effective API management practices. Companies that implement this standard now can benefit from stronger governance, a better developer experience, and more streamlined API lifecycle management. Combining this standard with platforms like Zuplo positions organizations to handle the expanding demands of modern API ecosystems with confidence and security.