Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Thinking About Schema.org's Relationship to API Discovery

DZone's Guide to

Thinking About Schema.org's Relationship to API Discovery

I will also start investing in folks employing Schema.org as part of their search engine strategies, making our APIs more discoverable to humans as well as other systems.

· Integration Zone
Free Resource

Modernize your application architectures with microservices and APIs with best practices from this free virtual summit series. Brought to you in partnership with CA Technologies.

I was following the discussion around adding a WebAPI class to Schema.org's core vocabulary and it got me to think more about the role Schema.org has to play with not just our API definitions but also significantly influencing API discovery — meaning that we should be using Schema.org as part of our OpenAPI definitions, providing us with a common vocabulary for communicating around our APIs, but also empowering the discovery of APIs. 

When I describe the relationship between Schema.org to API discovery, I'm talking about using the pending WebAPI class, but I'm also talking about using common Schema.org org within API definitions — something that will open the definitions to discovery because it employs a common schema.

I am also talking about how we leverage this vocabulary in our HTML pages, helping search engines like Google understand there is an API service available:

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "WebAPI",
  "name": "Your API Name",
  "description": "A full description of what your API is and does.",
  "documentation": "https://example.com/documentation/",
  "termsOfService": "https://example.com/tos/",
  "provider": {
    "@type": "Organization",
    "name": "API Evangelist"
  }
}
</script>

I will also be exploring how I can better leverage Schema.org in my APIs.json format, better leveraging a common vocabulary describing API operations, not just an individual API. I'm looking to expand the opportunities for discovering, not limit them. I would love all APIs to take a page from the hypermedia playbook and have a machine-readable index for each API with a set of links present with each response. But I also want folks to learn about APIs through Google, ensuring that they are indexed in a way that search engines can comprehend.

When it comes to API discovery, I am primarily invested in APIs.json (because it's my baby) describing API operations and OpenAPI to describe the surface area of an API; but I also want this to map to the very SEO-driven world that we operate in right now. I will keep investing time in helping folks use Schema.org in their API definitions (APIs.json and OpenAPI), but I will also start investing in folks employing JSON + LD and Schema.org as part of their search engine strategies (like above), making our APIs more discoverable to humans as well as other systems.

The Integration Zone is proudly sponsored by CA Technologies. Learn from expert microservices and API presentations at the Modernizing Application Architectures Virtual Summit Series.

Topics:
integration ,api ,api discovery ,schema.org

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

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}