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
Please enter at least three characters to search
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

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workkloads.

Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • Revolutionizing Financial Monitoring: Building a Team Dashboard With OpenObserve
  • Unlocking the Benefits of a Private API in AWS API Gateway
  • APIs for Logistics Orchestration: Designing for Compliance, Exceptions, and Edge Cases
  • Building Data Pipelines With Jira API

Trending

  • Performance Optimization Techniques for Snowflake on AWS
  • Build an MCP Server Using Go to Connect AI Agents With Databases
  • Accelerating AI Inference With TensorRT
  • Teradata Performance and Skew Prevention Tips
  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

  • Revolutionizing Financial Monitoring: Building a Team Dashboard With OpenObserve
  • Unlocking the Benefits of a Private API in AWS API Gateway
  • APIs for Logistics Orchestration: Designing for Compliance, Exceptions, and Edge Cases
  • Building Data Pipelines With Jira API

Partner Resources

×

Comments
Oops! Something Went Wrong

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
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!