Skip to main content

API

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


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

APIs can be created in two ways:

  • Code-based model: The API is generated automatically from your code.
  • Contract-based model: The API is created manually based on an API contract.

Within the Catalog, you can view the following API information:

  • A list of all APIs available in your account
  • The environments each API is associated with
  • API version details
  • API documentation

When you create an API in the Catalog, it can have one of the following statuses:

  1. Draft: The API is visible in the Service Catalog only to the Workspace that owns it. Any team member in the Workspace can publish the API, but it is not visible to the entire organization.
  2. Published: The API is displayed in the Catalog for the entire organization.
  3. Unpublished: The API is removed from the Catalog and cannot be published again. However, it remains accessible in the Catalog history.
tip

API references are 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.

Next Steps