Creating Internal and External SDKs

Creating Internal and External SDKs

To create two different versions of an SDK, one for internal use and one for external use, use JSONPath expressions in OpenAPI Overlays (a standard extension for modifying existing OpenAPI documents without changing the original). This approach dynamically targets and hides internal operations and parameters from the public SDK. The workflow.yaml file can be configured to include Overlays as part of the source definition.

Using the x-internal Extension

First, add an x-internal: true extension to all the operations, parameters, and other elements in the OpenAPI spec that should only be available in the internal SDK.

info:
  title: Sample API
  version: 1.0.0
  description: A sample API with internal paths and parameters.

paths:
  /public-resource:
    get:
      summary: Retrieve public data
      responses:
        '200':
          description: Public data response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string

  /internal-resource:
    x-internal: true   # This path is internal and should not be exposed externally
    get:
      summary: Retrieve internal data
      responses:
        '200':
          description: Internal data response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  internalInfo:
                    type: string
                    description: Internal information
                    x-internal: true  # This field is internal
        description: "This endpoint is restricted for internal staff management and not visible in public SDKs."

Using JSONPath Expressions in an Overlay

Next, use a JSONPath expression to remove all the internal paths and parameters from the SDK. This removal occurs specifically when generating the internal SDK.

info:
  title: Sample API Overlay
  version: 1.0.0
actions:
  - target: $.paths.*.*[?(@["x-internal"] == true)]
    remove: true
  - target: $.paths.*.*[?(@.properties[?(@["x-internal"] == true)])]
    remove: true

Define a workflow that generates both the internal and external SDKs.

workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  external-api:
    inputs:
      - location: ./api.yaml
    overlays:
      - location: ./external-overlay.yaml
  internal-api:
    inputs:
      - location: ./api.yaml
    overlays:
      - location: ./internal-overlay.yaml
targets:
  internal-sdk:
    target: python
    source: internal-api

  external-sdk:
    target: python
    source: external-api