openapi: 3.0.3 info: title: '@backstage/plugin-catalog-backend' version: '1' description: The Backstage backend plugin that provides the Backstage catalog license: name: Apache-2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html contact: {} servers: - url: / - url: catalog components: examples: {} headers: {} parameters: kind: name: kind in: path required: true allowReserved: true schema: type: string namespace: name: namespace in: path required: true allowReserved: true schema: type: string name: name: name in: path required: true allowReserved: true schema: type: string uid: name: uid in: path required: true allowReserved: true schema: type: string cursor: name: cursor in: query description: Cursor to a set page of results. required: false allowReserved: true schema: type: string minLength: 1 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: Restrict to just these fields in the response. 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 filter: name: filter in: query description: Filter for just the entities defined by this filter. 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 offset: name: offset in: query description: Number of records to skip in the query page. required: false allowReserved: true schema: type: integer minimum: 0 limit: name: limit in: query description: Number of records to return in the response. required: false allowReserved: true schema: type: integer minimum: 0 orderField: name: orderField in: query description: The fields to sort returned results by. 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 requestBodies: {} responses: ErrorResponse: description: An error response from the backend. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: 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: {} JsonObject: type: object properties: {} description: A type representing all allowed JSON object values. additionalProperties: {} MapStringString: type: object properties: {} additionalProperties: type: string description: Construct a type with a set of properties K of type T 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 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: {} 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 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. NullableEntity: 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. nullable: true 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 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 EntityFacet: type: object properties: value: type: string count: type: number required: - value - count additionalProperties: false EntityFacetsResponse: type: object properties: facets: type: object additionalProperties: type: array items: $ref: '#/components/schemas/EntityFacet' required: - facets additionalProperties: false Location: type: object properties: target: type: string type: type: string id: type: string required: - target - type - id description: Entity location for a specific entity. additionalProperties: false LocationSpec: type: object properties: target: type: string type: type: string required: - target - type description: Holds the entity location information. additionalProperties: false AnalyzeLocationExistingEntity: type: object properties: entity: $ref: '#/components/schemas/Entity' isRegistered: type: boolean location: $ref: '#/components/schemas/LocationSpec' required: - entity - isRegistered - location description: |- If the folder pointed to already contained catalog info yaml files, they are read and emitted like this so that the frontend can inform the user that it located them and can make sure to register them as well if they weren't already additionalProperties: false RecursivePartialEntityRelation: 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. description: A relation of a specific type to another entity in the catalog. additionalProperties: false RecursivePartialEntityMeta: allOf: - $ref: '#/components/schemas/JsonObject' - 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. description: Metadata fields common to all versions/kinds of entity. additionalProperties: false RecursivePartialEntity: type: object properties: apiVersion: type: string description: |- The version of specification format for this particular entity that this is written against. kind: type: string description: The high level entity type being described. metadata: $ref: '#/components/schemas/RecursivePartialEntityMeta' spec: $ref: '#/components/schemas/JsonObject' relations: type: array items: $ref: '#/components/schemas/RecursivePartialEntityRelation' description: The relations that this entity has with other entities. description: Makes all keys of an entire hierarchy optional. additionalProperties: false AnalyzeLocationEntityField: type: object properties: description: type: string description: |- A text to show to the user to inform about the choices made. Like, it could say "Found a CODEOWNERS file that covers this target, so we suggest leaving this field empty; which would currently make it owned by X" where X is taken from the codeowners file. value: type: string nullable: true state: type: string enum: - analysisSuggestedValue - analysisSuggestedNoValue - needsUserInput description: The outcome of the analysis for this particular field field: type: string description: |- e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the entity again if the user wants to change it required: - description - value - state - field additionalProperties: false AnalyzeLocationGenerateEntity: type: object properties: fields: type: array items: $ref: '#/components/schemas/AnalyzeLocationEntityField' entity: $ref: '#/components/schemas/RecursivePartialEntity' required: - fields - entity description: |- This is some form of representation of what the analyzer could deduce. We should probably have a chat about how this can best be conveyed to the frontend. It'll probably contain a (possibly incomplete) entity, plus enough info for the frontend to know what form data to show to the user for overriding/completing the info. additionalProperties: false AnalyzeLocationResponse: type: object properties: generateEntities: items: $ref: '#/components/schemas/AnalyzeLocationGenerateEntity' type: array existingEntityFiles: items: $ref: '#/components/schemas/AnalyzeLocationExistingEntity' type: array required: - generateEntities - existingEntityFiles additionalProperties: false LocationInput: type: object properties: type: type: string target: type: string required: - type - target 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 securitySchemes: JWT: type: http scheme: bearer bearerFormat: JWT paths: /refresh: post: operationId: RefreshEntity 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 /entities: get: operationId: GetEntities 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 /entities/by-uid/{uid}: get: operationId: GetEntityByUid 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' delete: operationId: DeleteEntityByUid 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' /entities/by-name/{kind}/{namespace}/{name}: get: operationId: GetEntityByName 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' /entities/by-name/{kind}/{namespace}/{name}/ancestry: get: operationId: GetEntityAncestryByName 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' /entities/by-refs: post: operationId: GetEntitiesByRefs 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 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 /entities/by-query: get: operationId: GetEntitiesByQuery 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/orderField' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/filter' - 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 /entity-facets: get: operationId: GetEntityFacets 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' /locations: post: operationId: CreateLocation description: Create a location for a given target. responses: '201': description: Created content: application/json: schema: type: object properties: exists: type: boolean entities: items: $ref: '#/components/schemas/Entity' type: array location: $ref: '#/components/schemas/Location' required: - entities - location '400': $ref: '#/components/responses/ErrorResponse' default: $ref: '#/components/responses/ErrorResponse' security: - {} - JWT: [] parameters: - in: query name: dryRun required: false allowReserved: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: target: type: string type: type: string required: - target - type get: operationId: GetLocations description: Get all locations responses: '200': description: Ok content: application/json: schema: type: array items: type: object properties: data: $ref: '#/components/schemas/Location' required: - data default: $ref: '#/components/responses/ErrorResponse' security: - {} - JWT: [] parameters: [] /locations/{id}: get: operationId: GetLocation description: Get a location by id. responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/Location' default: $ref: '#/components/responses/ErrorResponse' security: - {} - JWT: [] parameters: - in: path name: id required: true allowReserved: true schema: type: string delete: operationId: DeleteLocation description: Delete a location by id. responses: '204': description: No content '400': $ref: '#/components/responses/ErrorResponse' default: $ref: '#/components/responses/ErrorResponse' security: - {} - JWT: [] parameters: - in: path name: id required: true allowReserved: true schema: type: string /analyze-location: post: operationId: AnalyzeLocation description: Validate a given location. responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/AnalyzeLocationResponse' '400': $ref: '#/components/responses/ErrorResponse' default: $ref: '#/components/responses/ErrorResponse' security: - {} - JWT: [] parameters: [] requestBody: required: true content: application/json: schema: type: object properties: catalogFileName: type: string location: $ref: '#/components/schemas/LocationInput' required: - location /validate-entity: post: operationId: ValidateEntity description: Validate that a passed in entity has no errors in schema. responses: '200': description: Ok '400': description: Validation errors. content: application/json; charset=utf-8: 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