Dependencies

Our web routing and API development is defined by our OpenAPI specification. This specification defines the available web routes, API endpoints, handlers, requests, responses, and error objects.

This gives us a single source of truth, only one place that gives us up-to-date documentation, correct types, and a structured way to discuss routing.

Routes

In this example, a route of /api/config is defined. It requires an HTTP GET method. It’s response will be a WebConfig object type, also defined in our OpenAPI specification. The handler stub for writing the actual code for this endpoint in Go will be done in GetWebConfig.

  /config:
    get:
      summary: Get the web config
      operationId: GetWebConfig
      responses:
        '200':
          description: The current web config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebConfig'

Objects

For example, this is a definition for a SocialHandle object. It has three properties, platform, url, and icon. If you wanted to add another property, so you can return that in a response, or support accepting an additional property in a request, you must add that property to the object definition.

    SocialHandle:
      type: object
      properties:
        platform:
          type: string
        url:
          type: string
        icon:
          type: string

Generate Code

Before you can start building the actual endpoint code, you must execute the code generation step.

Run build/gen-api.sh https://github.com/owncast/owncast/blob/develop/build/gen-api.sh. It will perform the code generation step. It will take the OpenAPI spec and create the routes, handler stubs, and types required for any changes you made.

It will generate the code located in https://github.com/owncast/owncast/tree/develop/webserver/handlers/generated, and then can be committed with your changes.

Writing Handlers

Once the code generation is complete, a route will be ready, and an empty stub will be available for you to start writing your handler code using the new types that were also generated.

Documentation

This specification will automatically generate documentation that lives at owncast.online/api/latest