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 Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
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
Partner Zones AWS Cloud
by AWS Developer Relations
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
Partner Zones
AWS Cloud
by AWS Developer Relations
11 Monitoring and Observability Tools for 2023
Learn more
  1. DZone
  2. Data Engineering
  3. Databases
  4. Should You Craft Your Own API Definition Format?

Should You Craft Your Own API Definition Format?

Have you ever wondered if you should make your own API definition format? Here's a look at what you'll need to deliver if choosing this path.

Kin Lane user avatar by
Kin Lane
·
Feb. 25, 16 · Analysis
Like (1)
Save
Tweet
Share
3.67K Views

Join the DZone community and get the full member experience.

Join For Free

I have had multiple conversations with folks in the space who are building services and tooling for the API sector lately, where I was asked whether or not they should only be using existing API definition formats, or create their own API definition format that better represents what they are delivering. The reasoning is usually that they feel their own format would offer a more comprehensive approach than any single, existing API definition could--yet they fully understand the potential for adoption when they use existing formats like OpenAPI Spec and API Blueprint.

My answer to them is you deliver d) All The Above. I fully get that you will have your own unique view of the API space, and of what your tools and services will deliver, so you should be defining your own schema, but that you also can't ignore what is happening with OpenAPI Spec and API Blueprint either. There is a groundswell of services, tooling, and savvy API architects and developers using these existing API definition formats, and you do not want to be an island in this very connected sea.

Some examples of this already in motion can be found with APIMATIC and Runscope. Both of these providers fluently speak multiple existing API definition formats, but they also have their own, a custom format for describing what their service(s) brings to the table. I'd say the one difference is that Runscope is more focused on their own format, emphasizing the import/export in the Runscope version while APIMATIC is holding their version behind the scenes and emphasizing the use the existing API definition format of their own.

I think it is important that service providers flex both their own spec, as well as supporting existing formats like these providers do, even if it is just by using the API Transformer service. However, there is also an opportunity at the intersection of these two worlds with the x- extension for OpenAPI Spec. I honestly am unsure if API Blueprint has similar features, but will find out shortly. This is where I see API service providers merging their own custom schema, with the existing OpenAPI Spec. You can do the same within the API discovery format APIs.json when it comes to defining your API indexes and collections. 

As I talk OpenAPI Spec, API Blueprint, and APIs.json with more providers, I am finding that the majority of them are understanding the importance of supporting the leading formats, but also see aspects of the space that don't get covered in these formats, and want to better contribute their own vision of the space. I support both these paths, as long as we do not ever find ourselves cornered in our dogma silos, only believing in a single API definition format, or only supporting our own proprietary format that nobody else speaks. #Balance #Interroperability

API

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

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • What’s New in the Latest Version of Angular V15?
  • gRPC on the Client Side
  • Custom Validators in Quarkus
  • Collaborative Development of New Features With Microservices

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

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

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: