API

In this section, you will find more details about APIs on the Service Catalog.

In StackSpot, the API entity represents an Application exposed as an API in the API Catalog. Once an API is created and deployed, it will be available in the StackSpot Catalog.

The API can:

Use the code based model created automatically, if it does;
If it uses the contract-based model, you can create it manually.

In the Catalog, you can access the API information, see:

List of all APIs available in an account.
Environment that the APIs are connected to.
Version of the APIs.
Documentation.

When you create an API in the Catalog, it can have three statuses:

Draft: The API is displayed in the Service Catalog only for the Workspace that owns the created API. Any Workspace team member can publish it, but it is not displayed in the Catalog for the whole organization.
Published: The API shows up in the Catalog for the whole organization in this status.
Unpublished: The API is not displayed in the Catalog and can’t be published again. It is displayed in the Catalog history.

tip

API references are now ready for use.

Example

See below for an example of API content for a file in the OpenAPI 3.0 standard, which has the GET, POST, PUT, and DELETE methods. This file is responsible for the "materialization" of an API in the Service Catalog:

openapi: 3.0.0

info:
  title: My API
  description: This is my API
  version: 1.0.0

paths:
  /users:
    get:
      operationId: getUser
      description: Get a user
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
    post:
      operationId: createUser
      description: Create an user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid data
  /users/{userId}:
    get:
      operationId: getUserById
      description: Gets a user by ID
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
    put:
      operationId: updateUser
      description: Update an user
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Update an user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid data
    delete:
      operationId: deleteUser
      description: Delete an user
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
      responses:
        '204':
          description: Deleted user
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: João da Silva
        email:
          type: string
          example: joao.da.silva@example.com
        phone:
          type: string
          example: (11) 9999-9999
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

tip

The snippet above is just an example. You can customize it according to your API needs.

Example

Next Steps