Ingesting services using the FireHydrant API

With a populated Service Catalog, you have details on all of your services stored in a central location. You can import services into your FireHydrant service catalog manually; you can also ingest them using FireHydrant's API.

Creating bot tokens for API service ingestion

To access the FireHydrant API, you must authenticate with a bot token. (You must have owner permissions on your organization to see bot tokens.) Bot users allow you to interact with the FireHydrant API by using token-based authentication. To create bot tokens, log in to your organization and refer to the Bot users page.

Every request to the API is authenticated unless specified otherwise.

After creating your bot token, you can set up service ingestion with the API.

To get started:

1. In the FireHydrant left nav, expand Service Catalog. From the subsections, select Services. This opens a list of your existing services.
2. Click Catalog Settings, then Create catalog setting.

3. Enter a name and description of the service.
4. In the Provider field, choose API Only.
5. In the format field, select the format of the .yaml file (Backstage or OpsLevel) you want to send with your cURL request.
6. Click Create setting.
7. Next, you are returned to the Catalog settings page. The catalog you just added will appear in the list on this page. Click the name of your new catalog; this returns you to the Edit catalog settings page. for the API endpoint where you can post your data.

Example cURL request

You can base your cURL request for service ingestion on the following example. Note that this example is using a Backstage Component definition. To send OpsLevel, be sure to change your request format accordingly.

curl --location --request POST 'https://api.firehydrant.io/v1/catalogs/<CATALOG ID>/ingest' \
  --header 'Authorization: Bearer <YOUR BEARER TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "encoding": "application/json",
    "data": {
      "apiVersion": "backstage.io/v1alpha1",
      "kind": "Component",
      "metadata": {
        "namespace": "Spongebob",
        "name": "Component Service",
        "description": "I am a Backstage service component",
        "annotations": {
          "pagerduty.com/service-id": "EXAMPLE",
          "backstage.io/source-location": "url:https://github.com/octocat/Hello-World"
        },
        "labels": {
          "third-party": "true"
        }
      },
      "spec": {
        "type": "service",
        "lifecycle": "experimental",
        "owner": "team-name",
        "system": "whats-a-system",
        "links": [
          {
            "url": "https://admin.example-org.com/",
            "title": "Admin Dashboard",
            "icon": "dashboard"
          }
        ]
      }
    }
  }'