APIs.json APIs, Includes, and Network Properties

Since the beginning of the specification, APIs.json has had an “apis” property as well as an “includes” properties, providing a way to immediately index your APIs, or “include” a reference to other APIs.json indexes. The APIs.json specification is designed to be flexible in how you can define and organize your collections, but as I spend more time profiling and indexing APIs, I am finding a need to further expand on how APIs.json indexes work together in concert to provide a more federated approach to API discovery.

APIs.json APIs Property

The top level apis property for APIs.json is where you index your immediate APIs and publish in the index of your developer portal, where you might have 1-25 APIs indexed as part of your public operation—-maybe a few more (I stuffed 360+ in AWS). I am thinking that depending on the size of your APIs, that 25 is going to be my recommended limit. Of course you can index way more, but why? It really depends on who your audience is and what information you are looking to provide.

specificationVersion: '0.17'
aid: stripe
name: Stripe
description: >-
  Millions of companies of all sizes use Stripe online and in person to accept
  payments, send payouts, automate financial processes, and ultimately grow
image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
url: https://artisinal.apisjson.org/apis/stripe/apis.yml
created: 2023/10/06
modified: '2024-03-09'
tags: []
  - aid: stripe:stripe-balance-api
    name: Stripe Balance API
    description: >-
      This is an object representing your Stripe balance. You can retrieve it to
      see the balance currently on your Stripe account. You can also retrieve
      the balance history, which contains a list of transactions that
      contributed to the balance (charges, payouts, and so forth).
    image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
    humanURL: https://stripe.com/docs/api/balance
    baseURL: https://api.stripe.com
    tags: []
      - type: Documentation
        url: https://stripe.com/docs/api/balance
      - type: OpenAPI
        url: properties/balance-openapi-original.yml
      - type: APIs.io Search
        url: overlays/balance-openapi-search.yml
      - type: API Evangelist Ratings
        url: overlays/balance-openapi-api-evangelist-ratings.yml
  - type: Sign Up
    url: https://dashboard.stripe.com/register
  - type: Authentication
    url: https://stripe.com/docs/api/authentication
  - type: Blog
    url: https://stripe.com/blog
  - type: Status
    url: https://status.stripe.com/
  - type: Change Log
    url: https://stripe.com/docs/upgrades#api-versions
  - type: Terms of Service
    url: https://stripe.com/privacy
  - type: Support
    url: https://support.stripe.com/
  - type: APIs.io Search
    url: overlays/apis-io-search.yml
  - type: API Evangelist Ratings
    url: overlays/apis-io-search.yml
  - FN: APIs.json
    email: [email protected]

After breaking up APIs like AWS, Stripe, and others into many individual APIs indexed using the APIs.json apis property. It is the quickest way to organize them, but once I get them all tagged, I begin to think about other bounded contexts that I could also start breaking them down on. AWS has some pretty clear groupings, but Stripe and others take more domain expertise to think about to break down. I am opting to aggregate many APIs using the apis object before I begin to shard them even further—I will do more of that down the road.

APIs.json Includes Property

The APIs.json includes properties is how you can begin to shard and/or stitch together many different types of APIs. For example, payments API—you can publish an APIs.json with the name of Payments, and don’t have any APIs in the apis properties, and you just link to Stripe, PayPal, and other payment APIs. You could use it for lines of business or any other meaningful bounded context for an industry.

specificationVersion: '0.17'
aid: payments
name: APIs.io - Payments
description: The APIs that make payments possible, as well as a number of other related
image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
url: https://payments.apis.io/apis.json
created: 2024/04/13
modified: 2024/04/13
- Payments
- name: Adyen
  url: https://raw.githubusercontent.com/api-search/payments/main/_apis/adyen/apis.md
- name: Paypal
  url: https://raw.githubusercontent.com/api-search/payments/main/_apis/paypal/apis.md
- name: Stripe
  url: https://raw.githubusercontent.com/api-search/payments/main/_apis/stripe/apis.md
- FN: APIs.io
  email: [email protected]

I tend to profile API providers using a single APIs.json, leveraging the apis properties, but then based upon tags, begin to shard and organize them into other more meaningful collections. I am doing this with properties like SDKs or plans and pricing pages, as well as pushing the boundaries based upon different ways I am rating APIs. The APIs.json includes property is how I am putting the federated in our approach to APis.io.

APIs.json Network Property

We haven’t officially added this property to the APIs.json specification, but I’ll craft up a proposal to add with version .18 of the specification. I needed this network property to further “network” the different search nodes I was deploying as part of sharding my APIs.json profiling work. I needed a way to articulate the network of APIs I am managing, helping me power my search engine across the growing number of Apis I was profiling.

specificationVersion: '0.18'
aid: explore
name: APIs.io
description: The first API search engine.
image: https://kinlane-productions2.s3.amazonaws.com/apis-json/apis-json-logo.jpg
url: https://explore.apis.io/apis.json
created: 2024/04/13
modified: 2024/04/13
- APIs
- Search
- name: Artificial Intelligence
  url: https://ai.apis.io/apis.json
- name: Banking
  url: https://banking.apis.io/apis.json
- name: Cloud
  url: https://cloud.apis.io/apis.json
- name: Code
  url: https://code.apis.io/apis.json
- name: Commerce
  url: https://commerce.apis.io/apis.json
- name: Documents
  url: https://documents.apis.io/apis.json
- name: Financial
  url: https://financial.apis.io/apis.json
- name: Infrastructure
  url: https://infrastructure.apis.io/apis.json
- name: Messaging
  url: https://messaging.apis.io/apis.json
- name: Payments
  url: https://payments.apis.io/apis.json
- name: Travel
  url: https://travel.apis.io/apis.json
- name: Videos
  url: https://videos.apis.io/apis.json
- FN: APIs.io
  email: [email protected]

I am going to stress test this properly over the next couple of weeks. I am thinking that I am going to need to add a tags property to both the includes and network property so I can further organize the networks into groups. IDK. I might just get more strict with how I roll out and group my API search nodes. It really depends on the tags accumulated for the APIs profiling, and how they cluster together as I continue the work.

Federating and Localizing

This round of APIs.io exploration is all about federating and localizing the search engine, demonstrating the potential of the APIs.json format. I am working hard to find the sweet spot when it comes to working with many different APIs. One of the keys to success I am finding is reducing the cognitive load with anything I am doing across the hundreds, and now thousands of APIs I am profiling for APis.io. My approach to localizing and federating APIs as part of APIs.io is also how I’d recommend larger enterprises approach their own API discovery internally. Keeping things small and manageable along lines of business, team boundaries, work streams, and other organically forming bounded contexts.

I have probably another fifteen search nodes to deploy using the APIs I have already profiled in my Artisanal work. I just wanted to see if it was possible to shard and network things, and produce a federated search mechanism. So far, so good. Now I just want to pile a bunch more APIs on top of it. I need to share individual APIs like GitLab, but also additional dimensions of API discovery like shipping, government, and the top categories you’d expect with an API search engine. Next, I am looking to pile on about 2-3K APIs across 25+ search nodes, with a single federated search, but also a more powerful API-driven cloud search after I ingest all of my nodes into a database. Then I’ll document my network and search websites behind APIs.io to help make them more forkable and usable anywhere GItHub pages or even Jekyll will run.