Backstage Entity API

openapi: 3.2.0
info:
  title: catalog Entity API
  version: '1'
  description: The API surface consists of a few distinct groups of functionality.
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  contact: {}
servers:
- url: /
tags:
- name: Entity
paths:
  /refresh:
    post:
      operationId: RefreshEntity
      tags:
      - Entity
      description: Refresh the entity related to entityRef.
      responses:
        '200':
          description: Refreshed
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authorizationToken:
                  type: string
                entityRef:
                  type: string
                  description: The reference to a single entity that should be refreshed
              required:
              - entityRef
              description: Options for requesting a refresh of entities in the catalog.
              additionalProperties: false
      summary: Refresh entity
      x-summary-source: derived
  /entities:
    get:
      operationId: GetEntities
      tags:
      - Entity
      description: Get all entities matching a given filter.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/after'
      - name: order
        in: query
        allowReserved: true
        required: false
        schema:
          type: array
          items:
            type: string
      summary: Get entities
      x-summary-source: derived
  /entities/by-uid/{uid}:
    get:
      operationId: GetEntityByUid
      tags:
      - Entity
      description: Get a single entity by the UID.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/uid'
      summary: Get entity by uid
      x-summary-source: derived
    delete:
      operationId: DeleteEntityByUid
      tags:
      - Entity
      description: Delete a single entity by UID.
      responses:
        '204':
          description: Deleted successfully.
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/uid'
      summary: Delete entity by uid
      x-summary-source: derived
  /entities/by-name/{kind}/{namespace}/{name}:
    get:
      operationId: GetEntityByName
      tags:
      - Entity
      description: Get an entity by an entity ref.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/kind'
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      summary: Get entity by name
      x-summary-source: derived
  /entities/by-name/{kind}/{namespace}/{name}/ancestry:
    get:
      operationId: GetEntityAncestryByName
      tags:
      - Entity
      description: Get an entity's ancestry by entity ref.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityAncestryResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/kind'
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      summary: Get entity ancestry by name
      x-summary-source: derived
  /entities/by-refs:
    post:
      operationId: GetEntitiesByRefs
      tags:
      - Entity
      description: Get a batch set of entities given an array of entityRefs.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesBatchResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              required:
              - entityRefs
              properties:
                entityRefs:
                  type: array
                  items:
                    type: string
                fields:
                  type: array
                  items:
                    type: string
                query:
                  $ref: '#/components/schemas/JsonObject'
            examples:
              Fetch Backstage entities:
                value:
                  entityRefs:
                  - component:default/backstage
                  - api:default/backstage
              Fetch annotations for backstage entity:
                value:
                  entityRefs:
                  - component:default/backstage
                  fields:
                  - metadata.annotations
      parameters:
      - $ref: '#/components/parameters/filter'
      summary: Get entities by refs
      x-summary-source: derived
  /entities/by-query:
    get:
      operationId: GetEntitiesByQuery
      tags:
      - Entity
      description: Search for entities by a given query.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters:
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/orderField'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/totalItems'
      - name: fullTextFilterTerm
        in: query
        description: Text search term.
        required: false
        allowReserved: true
        schema:
          type: string
      - name: fullTextFilterFields
        in: query
        description: A comma separated list of fields to sort returned results by.
        required: false
        allowReserved: true
        schema:
          type: array
          items:
            type: string
        explode: false
        style: form
      summary: Get entities by query
      x-summary-source: derived
    post:
      operationId: QueryEntitiesByPredicate
      tags:
      - Entity
      description: Query entities using predicate-based filters.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitiesQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cursor:
                  type: string
                limit:
                  type: number
                offset:
                  type: number
                orderBy:
                  type: array
                  items:
                    type: object
                    required:
                    - field
                    - order
                    properties:
                      field:
                        type: string
                      order:
                        type: string
                        enum:
                        - asc
                        - desc
                fullTextFilter:
                  type: object
                  properties:
                    term:
                      type: string
                    fields:
                      type: array
                      items:
                        type: string
                fields:
                  type: array
                  items:
                    type: string
                totalItems:
                  type: string
                  enum:
                  - include
                  - exclude
                  description: 'Controls whether the response''s `totalItems` field is

                    computed. Pass `exclude` to skip the count when the caller

                    doesn''t need it. Defaults to `include`.

                    '
                query:
                  $ref: '#/components/schemas/JsonObject'
      summary: Query entities by predicate
      x-summary-source: derived
  /entity-facets:
    get:
      operationId: GetEntityFacets
      tags:
      - Entity
      description: Get all entity facets that match the given filters.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityFacetsResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      parameters:
      - in: query
        name: facet
        required: true
        allowReserved: true
        schema:
          type: array
          items:
            type: string
        examples:
          Entities by kind:
            value:
            - kind
          Entities by spec type:
            value:
            - spec.type
      - $ref: '#/components/parameters/filter'
      summary: Get entity facets
      x-summary-source: derived
    post:
      operationId: QueryEntityFacetsByPredicate
      tags:
      - Entity
      description: Get entity facets using predicate-based filters.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityFacetsResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - {}
      - JWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - facets
              properties:
                facets:
                  type: array
                  items:
                    type: string
                query:
                  $ref: '#/components/schemas/JsonObject'
      summary: Query entity facets by predicate
      x-summary-source: derived
  /validate-entity:
    post:
      operationId: ValidateEntity
      tags:
      - Entity
      description: Validate that a passed in entity has no errors in schema.
      responses:
        '200':
          description: Ok
        '400':
          description: Validation errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        message:
                          type: string
                      required:
                      - name
                      - message
                      additionalProperties: {}
                required:
                - errors
      security:
      - {}
      - JWT: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                location:
                  type: string
                entity:
                  type: object
                  additionalProperties: {}
              required:
              - location
              - entity
      summary: Validate entity
      x-summary-source: derived
components:
  parameters:
    uid:
      name: uid
      in: path
      required: true
      schema:
        type: string
    totalItems:
      name: totalItems
      in: query
      description: 'Controls whether the response''s `totalItems` field is computed. Computing

        the total may be expensive for large catalogs; pass `exclude` if the

        caller does not need it (e.g. cursor-paginated UIs that only display the

        count cosmetically). Defaults to `include`. New values may be added in

        the future, such as an approximate mode.

        '
      required: false
      allowReserved: true
      schema:
        type: string
        enum:
        - include
        - exclude
    namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
    cursor:
      name: cursor
      in: query
      description: "You may pass the `cursor` query parameters to perform cursor based pagination\nthrough the set of entities. The value of `cursor` will be returned in the response, under the `pageInfo` property:\n\n```json\n  \"pageInfo\": {\n    \"nextCursor\": \"a-cursor\",\n    \"prevCursor\": \"another-cursor\"\n  }\n```\n\nIf `nextCursor` exists, it can be used to retrieve the next batch of entities. Following the same approach,\nif `prevCursor` exists, it can be used to retrieve the previous batch of entities.\n\n- [`filter`](#filtering), for selecting only a subset of all entities\n- [`fields`](#field-selection), for selecting only parts of the full data\n  structure of each entity\n- `limit` for limiting the number of entities returned (20 is the default)\n- [`orderField`](#ordering), for deciding the order of the entities\n- `fullTextFilter`\n  **NOTE**: [`filter`, `orderField`, `fullTextFilter`] and `cursor` are mutually exclusive. This means that,\n  it isn't possible to change any of [`filter`, `orderField`, `fullTextFilter`] when passing `cursor` as query parameters,\n  as changing any of these properties will affect pagination. If any of `filter`, `orderField`, `fullTextFilter` is specified together with `cursor`, only the latter is taken into consideration.\n"
      required: false
      allowReserved: true
      schema:
        type: string
        minLength: 1
    limit:
      name: limit
      in: query
      description: Number of records to return in the response.
      required: false
      allowReserved: true
      schema:
        type: integer
        minimum: 0
    offset:
      name: offset
      in: query
      description: Number of records to skip in the query page.
      required: false
      allowReserved: true
      schema:
        type: integer
        minimum: 0
    kind:
      name: kind
      in: path
      required: true
      schema:
        type: string
    orderField:
      name: orderField
      in: query
      description: 'By default the entities are returned ordered by their internal uid. You can

        customize the `orderField` query parameters to affect that ordering.


        For example, to return entities by their name:


        `/entities/by-query?orderField=metadata.name,asc`


        Each parameter can be followed by `asc` for ascending lexicographical order or

        `desc` for descending (reverse) lexicographical order.

        '
      required: false
      allowReserved: true
      schema:
        type: array
        items:
          type: string
          description: A two-item tuple of [field, order].
      explode: true
      style: form
      examples:
        Order ascending by name:
          value:
          - metadata.name,asc
        Order descending by owner:
          value:
          - spec.owner,desc
    filter:
      name: filter
      in: query
      description: "You can pass in one or more filter sets that get matched against each entity.\nEach filter set is a number of conditions that all have to match for the\ncondition to be true (conditions effectively have an AND between them). At least\none filter set has to be true for the entity to be part of the result set\n(filter sets effectively have an OR between them).\n\nExample:\n\n```text\n/entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type\n\n  Return entities that match\n\n    Filter set 1:\n      Condition 1: kind = user\n                  AND\n      Condition 2: metadata.namespace = default\n\n    OR\n\n    Filter set 2:\n      Condition 1: kind = group\n                  AND\n      Condition 2: spec.type exists\n```\n\nEach condition is either on the form `<key>`, or on the form `<key>=<value>`.\nThe first form asserts on the existence of a certain key (with any value), and\nthe second asserts that the key exists and has a certain value. All checks are\nalways case _insensitive_.\n\nIn all cases, the key is a simplified JSON path in a given piece of entity data.\nEach part of the path is a key of an object, and the traversal also descends\nthrough arrays. There are two special forms:\n\n- Array items that are simple value types (such as strings) match on a key-value\n  pair where the key is the item as a string, and the value is the string `true`\n- Relations can be matched on a `relations.<type>=<targetRef>` form\n\nLet's look at a simplified example to illustrate the concept:\n\n```json\n{\n  \"a\": {\n    \"b\": [\"c\", { \"d\": 1 }],\n    \"e\": 7\n  }\n}\n```\n\nThis would match any one of the following conditions:\n\n- `a`\n- `a.b`\n- `a.b.c`\n- `a.b.c=true`\n- `a.b.d`\n- `a.b.d=1`\n- `a.e`\n- `a.e=7`\n\nSome more real world usable examples:\n\n- Return all orphaned entities:\n\n  `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true`\n\n- Return all users and groups:\n\n  `/entities/by-query?filter=kind=user&filter=kind=group`\n\n- Return all service components:\n\n  `/entities/by-query?filter=kind=component,spec.type=service`\n\n- Return all entities with the `java` tag:\n\n  `/entities/by-query?filter=metadata.tags.java`\n\n- Return all users who are members of the `ops` group (note that the full\n  [reference](references.md) of the group is used):\n\n  `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`\n"
      required: false
      allowReserved: true
      schema:
        type: array
        items:
          type: string
      examples:
        Get groups:
          value:
          - kind=group
        Get orphaned components:
          value:
          - kind=component,metadata.annotations.backstage.io/orphan=true
    name:
      name: name
      in: path
      required: true
      schema:
        type: string
    after:
      name: after
      in: query
      description: Pointer to the previous page of results.
      required: false
      allowReserved: true
      schema:
        type: string
        minLength: 1
    fields:
      name: fields
      in: query
      description: "By default the full entities are returned, but you can pass in a `fields` query\nparameter which selects what parts of the entity data to retain. This makes the\nresponse smaller and faster to transfer, and may allow the catalog to perform\nmore efficient queries.\n\nThe query parameter value is a comma separated list of simplified JSON paths\nlike above. Each path corresponds to the key of either a value, or of a subtree\nroot that you want to keep in the output. The rest is pruned away. For example,\nspecifying `?fields=metadata.name,metadata.annotations,spec` retains only the\n`name` and `annotations` fields of the `metadata` of each entity (it'll be an\nobject with at most two keys), keeps the entire `spec` unchanged, and cuts out\nall other roots such as `relations`.\n\nSome more real world usable examples:\n\n- Return only enough data to form the full ref of each entity:\n\n  `/entities/by-query?fields=kind,metadata.namespace,metadata.name`\n"
      required: false
      allowReserved: true
      explode: false
      schema:
        type: array
        items:
          type: string
      examples:
        Get name and the entire relations collection:
          value:
          - metadata.name
          - relations
        Get kind, name and namespace:
          value:
          - kind
          - metadata.name
          - metadata.namespace
  schemas:
    EntityFacetsResponse:
      type: object
      properties:
        facets:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EntityFacet'
      required:
      - facets
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            name:
              type: string
            message:
              type: string
            stack:
              type: string
            code:
              type: string
          required:
          - name
          - message
        request:
          type: object
          properties:
            method:
              type: string
            url:
              type: string
          required:
          - method
          - url
        response:
          type: object
          properties:
            statusCode:
              type: number
          required:
          - statusCode
      required:
      - error
      - response
      additionalProperties: {}
    Entity:
      type: object
      properties:
        relations:
          type: array
          items:
            $ref: '#/components/schemas/EntityRelation'
          description: The relations that this entity has with other entities.
        spec:
          $ref: '#/components/schemas/JsonObject'
        metadata:
          $ref: '#/components/schemas/EntityMeta'
        kind:
          type: string
          description: The high level entity type being described.
        apiVersion:
          type: string
          description: 'The version of specification format for this particular entity that

            this is written against.'
      required:
      - metadata
      - kind
      - apiVersion
      description: The parts of the format that's common to all versions/kinds of entity.
    JsonObject:
      type: object
      properties: {}
      description: A type representing all allowed JSON object values.
      additionalProperties: {}
    EntitiesBatchResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NullableEntity'
          description: 'The list of entities, in the same order as the refs in the request. Entries

            that are null signify that no entity existed with that ref.'
      required:
      - items
      additionalProperties: false
    EntityAncestryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              parentEntityRefs:
                items:
                  type: string
                type: array
              entity:
                $ref: '#/components/schemas/Entity'
            required:
            - parentEntityRefs
            - entity
        rootEntityRef:
          type: string
      required:
      - items
      - rootEntityRef
      additionalProperties: false
    EntityLink:
      type: object
      properties:
        type:
          type: string
          description: An optional value to categorize links into specific groups
        icon:
          type: string
          description: An optional semantic key that represents a visual icon.
        title:
          type: string
          description: An optional descriptive title for the link.
        url:
          type: string
          description: The url to the external site, document, etc.
      required:
      - url
      description: A link to external information that is related to the entity.
      additionalProperties: false
    EntitiesQueryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
          description: The list of entities paginated by a specific filter.
        totalItems:
          type: number
        pageInfo:
          type: object
          properties:
            nextCursor:
              type: string
              description: The cursor for the next batch of entities.
            prevCursor:
              type: string
              description: The cursor for the previous batch of entities.
      required:
      - items
      - totalItems
      - pageInfo
      additionalProperties: false
    MapStringString:
      type: object
      properties: {}
      additionalProperties:
        type: string
      description: Construct a type with a set of properties K of type T
    EntityRelation:
      type: object
      properties:
        targetRef:
          type: string
          description: The entity ref of the target of this relation.
        type:
          type: string
          description: The type of the relation.
      required:
      - targetRef
      - type
      description: A relation of a specific type to another entity in the catalog.
      additionalProperties: false
    NullableEntity:
      anyOf:
      - type: object
        properties:
          relations:
            type: array
            items:
              $ref: '#/components/schemas/EntityRelation'
            description: The relations that this entity has with other entities.
          spec:
            $ref: '#/components/schemas/JsonObject'
          metadata:
            $ref: '#/components/schemas/EntityMeta'
          kind:
            type: string
            description: The high level entity type being described.
          apiVersion:
            type: string
            description: 'The version of specification format for this particular entity that

              this is written against.'
        required:
        - metadata
        - kind
        - apiVersion
        description: The parts of the format that's common to all versions/kinds of entity.
      - type: 'null'
    EntityMeta:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/EntityLink'
          description: A list of external hyperlinks related to the entity.
        tags:
          type: array
          items:
            type: string
          description: 'A list of single-valued strings, to for example classify catalog entities in

            various ways.'
        annotations:
          $ref: '#/components/schemas/MapStringString'
        labels:
          $ref: '#/components/schemas/MapStringString'
        description:
          type: string
          description: 'A short (typically relatively few words, on one line) description of the

            entity.'
        title:
          type: string
          description: 'A display name of the entity, to be presented in user interfaces instead

            of the `name` property above, when available.

            This field is sometimes useful when the `name` is cumbersome or ends up

            being perceived as overly technical. The title generally does not have

            as stringent format requirements on it, so it may contain special

            characters and be more explanatory. Do keep it very short though, and

            avoid situations where a title can be confused with the name of another

            entity, or where two entities share a title.

            Note that this is only for display purposes, and may be ignored by some

            parts of the code. Entity references still always make use of the `name`

            property, not the title.'
        namespace:
          type: string
          description: The namespace that the entity belongs to.
        name:
          type: string
          description: 'The name of the entity.

            Must be unique within the catalog at any given point in time, for any

            given namespace + kind pair. This value is part of the technical

            identifier of the entity, and as such it will appear in URLs, database

            tables, entity references, and similar. It is subject to restrictions

            regarding what characters are allowed.

            If you want to use a different, more human readable string with fewer

            restrictions on it in user interfaces, see the `title` field below.'
        etag:
          type: string
          description: 'An opaque string that changes for each update operation to any part of

            the entity, including metadata.

            This field can not be set by the user at creation time, and the server

            will reject an attempt to do so. The field will be populated in read

            operations. The field can (optionally) be specified when performing

            update or delete operations, and the server will then reject the

            operation if it does not match the current stored value.'
        uid:
          type: string
          description: 'A globally unique ID for the entity.

            This field can not be set by the user at creation time, and the server

            will reject an attempt to do so. The field will be populated in read

            operations. The field can (optionally) be specified when performing

            update or delete operations, but the server is free to reject requests

            that do so in such a way that it breaks semantics.'
      required:
      - name
      description: Metadata fields common to all versions/kinds of entity.
      additionalProperties: {}
    EntityFacet:
      type: object
      properties:
        value:
          type: string
        count:
          type: number
      required:
      - value
      - count
      additionalProperties: false
  responses:
    ErrorResponse:
      description: An error response from the backend.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT