Debian Code Search API keys

Why require API keys at all?

Our API keys encode an (encrypted) identity, which makes all API requests programmatically identifiable. This makes Debian Code Search more available:

  1. When the service would otherwise be overwhelmed by requests, instead of turning off the entire API, we can throttle or reject only requests coming in with an individual API key.
  2. Because the keys are personalized, we can reach out to the right person and resolve any issues as quickly as possible.

Your personal API key

🔑 After you log in via the salsa.debian.org GitLab instance,
you will see a personal API key file for download here.

If you need a non-personal API key for a CLI tool, web service, etc.,
please reach out to stapelberg@debian.org.

OpenAPI Specification, Client Libraries, Docs, Examples

The Debian Code Search API is described in an OpenAPI specification (OAS),
which you can use with various Swagger tools:

Documentation Browser

For your convenience, here is an embedded Swagger UI documentation browser:

(Embedded Swagger UI loading…)

OpenAPI spec URLs

This table lists all available Debian Code Search OpenAPI spec URLs:

Format OpenAPI version URL Note
YAML OpenAPI 3 https://codesearch.debian.net/openapi.yaml Preferred
JSON OpenAPI 3 https://codesearch.debian.net/openapi.json
YAML OpenAPI 2 https://codesearch.debian.net/openapi2.yaml Canonical
JSON OpenAPI 2 https://codesearch.debian.net/openapi2.json

For new developments, if supported in your environment, prefer using OpenAPI 3 in either YAML (hand-written) or JSON (automatically converted).

OpenAPI 2 is our canonical spec because one can derive OpenAPI 3 from it, but the other way around is not possible. As of September 2020, it is worthwhile to keep OpenAPI 2 around because some tools offer broader compatibility with it.

Table Of Contents
  1. Why require API keys at all?
  2. Your personal API key
  3. OpenAPI
    1. Documentation Browser
    2. Spec URLs