Each API on the Hub can have an associated field named externalCustomId. You can set the value of this field to your company's API ID. You can then search for the API on Rapid using your custom ID.

📘

Programmatic access only

External custom IDs are available programmatically using the REST and GraphQL Platform APIs. By default, they are not shown in Rapid's user interfaces.

Creating an API that has a custom ID

The createApi mutation allows you to include the externalCustomId in the input:

mutation createApi($apiCreateInput: ApiCreateInput!) {
  createApi(api: $apiCreateInput) {
    id
    externalCustomId
  }
}

{
  "apiCreateInput": {
     "name": "REST API with Custom ID",
     "category": "Other",
     "description": "REST API with an external custom ID.",
     "version": {
        "name": "1.0"
     },
    "externalCustomId": "my-custom-id-01"
  }
}

📘

REST Platform API

Instead of the GraphQL Platform API example above, you can use the Create API endpoint of the REST Platform API and set a value in the externalCustomId field.

Updating or adding a custom ID to an existing API

Use the updateApi mutation to add or change an externalCustomId for an API.

📘

Environment admins only

Only users with environment admin permissions can add or update an externalCustomId using the updateApi mutation.

mutation updateApi($api: ApiUpdateInput!) {
   updateApi(api: $api) {
     name
     id
     externalCustomId
   }
}

{
  "api": {
    "id": "[your API id]",
    "externalCustomId": "my-custom-id-01a"
  }
}

There is no REST Platform API equivalent of the mutation above.

Obtaining an API's custom ID

Use the api query to read an API's custom ID. In the variables, you must specify Rapid's API ID.

query readAPI($apiId: ID!) {
  api(id: $apiId) {
    id
    externalCustomId
  }
}

{
  "apiId": "api_15d502af-e297-4f9d-b275-xxxxxxxxxx"
}

📘

REST Platform API

Instead of the GraphQL Platform API example above, you can use the Get API endpoint of the REST Platform API and obtain the value of the externalCustomId field.

Searching for an API by custom ID

Use the apis query to search for the API with an external custom ID. You can specify more than one external custom ID to search for multiple APIs.

query Apis ($customId: [ID!] ) {
  apis(
    where: {
      externalCustomIds: $customId
    }
  ) {
    edges {
      node {
        id
        externalCustomId
        name
      }
    }
  }
}

{
  "customId": [
    "my-custom-id-01"
  ]
}

📘

REST Platform API

Instead of the GraphQL Platform API example above, you can use the Get API by external custom ID endpoint of the REST Platform API to search for the API by externalCustomId.