feat(catalog): add entity to describe APIs

2020-07-23 14:42:56 +02:00
parent 611201ee9f
commit b5f8aa89b8
8 changed files with 642 additions and 0 deletions
@@ -14,6 +14,8 @@ humans. However, the structure and semantics is the same in both cases.
 - [Common to All Kinds: The Envelope](#common-to-all-kinds-the-envelope)
 - [Common to All Kinds: The Metadata](#common-to-all-kinds-the-metadata)
 - [Kind: Component](#kind-component)
+- [Kind: Template](#kind-template)
+- [Kind: API](#kind-api)

 ## Overall Shape Of An Entity

@@ -422,3 +424,76 @@ specify relative to the `template.yaml` definition.

 This is also particularly useful when you have multiple template definitions in
 the same repository but only a single `template.yaml` registered in backstage.
+
+## Kind: API
+
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `API`                   |
+
+An API describes an interface that can be exposed by a component. The API can be
+defined in different formats, like [OpenAPI](https://swagger.io/specification/),
+[AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/),
+[gRPC](https://developers.google.com/protocol-buffers), or other formats.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: artist-api
+  description: Retrieve artist details
+spec:
+  type: openapi
+  definition: |
+    openapi: "3.0.0"
+    info:
+      version: 1.0.0
+      title: Artist API
+      license:
+        name: MIT
+    servers:
+      - url: http://artist.spotify.net/v1
+    paths:
+      /artists:
+        get:
+          summary: List all artists
+    ...
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `API`, respectively.
+
+### `spec.type` [required]
+
+The type of the API definition as a string, e.g. `openapi`. This field is
+required.
+
+The software catalog accepts any type value, but an organisation should take
+great care to establish a proper taxonomy for these. Tools including Backstage
+itself may read this field and behave differently depending on its value. For
+example, an OpenAPI type API may be displayed using an OpenAPI viewer tooling in
+the Backstage interface.
+
+The current set of well-known and common values for this field is:
+
+- `openapi` - An API definition in YAML or JSON format based on the
+  [OpenAPI](https://swagger.io/specification/) version 2 or version 3 spec.
+- `asyncapi` - An API definition based on the
+  [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/) spec.
+- `grpc` - An API definition based on
+  [Protocol Buffers](https://developers.google.com/protocol-buffers) to use with
+  [gRPC](https://grpc.io/).
+
+### `spec.definition` [required]
+
+The definition of the API, based on the format defined by `spec.type`. This
+field is required.