DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

SBOMs are essential to circumventing software supply chain attacks, and they provide visibility into various software components.

Related

  • Analysis of the Data Processing Framework of Pandas and Snowpark Pandas API
  • How to Build a Real API Gateway With Spring Cloud Gateway and Eureka
  • Master AI Development: The Ultimate Guide to LangChain, LangGraph, LangFlow, and LangSmith
  • Building an AI Nutrition Coach With OpenAI, Gradio, and gTTS

Trending

  • How We Broke the Monolith (and Kept Our Sanity): Lessons From Moving to Microservices
  • Top 5 Trends in Big Data Quality and Governance in 2025
  • Exploring Data Redaction Enhancements in Oracle Database 23ai
  • When Caches Collide: Solving Race Conditions in Fare Updates
  1. DZone
  2. Data Engineering
  3. Databases
  4. Organizing My APIs Using OpenAPI Tags

Organizing My APIs Using OpenAPI Tags

It's time to get organized.

By 
Kin Lane user avatar
Kin Lane
·
Jun. 24, 19 · Analysis
Likes (4)
Comment
Save
Tweet
Share
14.0K Views

Join the DZone community and get the full member experience.

Join For Free

I like my OpenAPI tags. Honestly, I like tags in general. Almost every API resource I design ends up having some sort of tagging layer. To help me organize my world, I have a centralized tagging vocabulary that I use across my JSON Schema, OpenAPI, and AsyncAPI to help me group, organize, filter, publish, and maintain my catalog of API and schema resources.

The tag object for the OpenAPI specification is pretty basic, allowing you to add tags for an entire API contract, as well as apply them to each individual API method. Tooling, such as API documentation, uses these tags to group your API resources, allowing you to break down your resources into logical bounded contexts. It is a pretty basic way of defining tags that can go a long way, depending on how creative you want to get. I am extending tags with an OpenAPI vendor extension, but I also see that there is an issue submitted suggesting they move the specification forward by allowing for the nesting of tags — potentially taking OpenAPI tagging to the next level.

I’m allowing for a handful of extensions to the OpenAPI specification to accomplish the following:

  • Tag Grouping — Help me nest and build multiple tiers of tags for organization APIs.
  • Tag Sorting — Allowing me to define a sort order that goes beyond an alphabetical list.

I am building listing, reporting, and other management tools based up OpenAPI tagging to help me in the following areas:

  • Tag Usage — Reporting how many resources are available for each tag and tag group.
  • Tag Cleanup — Helping me de-dupe, rename, deal with plural challenges, etc.
  • Tag Translations — Translating old tags into new tags, helping keep things meaningful.
  • Tag Clouds — Generating D3.js tag clouds from the tags applied to API resources.
  • Packages — Deployment of NPM packages based upon different bounded contexts defined by tags.

I am applying tags to the following specifications, stretching my OpenAPI tagging approach to be more about a universal way to organize all my resources:

  • JSON Schema — All schema objects have tags to keep organized.
  • OpenAPI — Each API method have tags, for easy grouping.
  • AsyncAPI — Each pub/sub, event, and message API have APIs.
  • APIs.json — Collections of APIs have tags for discoverability.

Tags are an important dimension of API discoverability when it comes to my API definitions. They provide rich metadata that I can use to make sense of my API infrastructure. Without them, the quality of my API definitions tend to trend lower. By evolving the tagging schema, and investing in tooling to help me make sense across the API definitions I’m depending on, I can push the boundaries of how I tag and evolve it to be the core of how I manage my API definitions.

I’ll keep watching how others are tagging their APIs, although I don’t see too much innovation and low levels of usage by other API providers as part of their API definitions. I’ll also keep an eye out for other ways in which tag schema are being extended, helping potentially define the future of how the leading API specifications enable tagging. I have a short list of tooling I am developing to help make my life easier, but I’m working hard to just make sure I’m applying tags across my API resources in a consistent way. I find this is the most valuable aspect of API tagging, but eventually, I’m guessing that the tooling will make the real difference when it comes to slicing and dicing, and making sense of my API infrastructure at scale.

API

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Analysis of the Data Processing Framework of Pandas and Snowpark Pandas API
  • How to Build a Real API Gateway With Spring Cloud Gateway and Eureka
  • Master AI Development: The Ultimate Guide to LangChain, LangGraph, LangFlow, and LangSmith
  • Building an AI Nutrition Coach With OpenAI, Gradio, and gTTS

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • [email protected]

Let's be friends: