api-compact.yaml

# Enterprise IDA: upstream API definitions, including vendor extensions.
# Note, while this document is not strictly to Swagger spec, each HTTP method's
# definition _must_ be to spec or the downstream ref will fail.
#
# Clients must include an Authorization header with OAuth2 access token in order to communicate:
#   Authorization: JWT {access_token}
#
#
# Available service endpoints -- note that alternate endpoints may be presented at the API Gateway tier
#   /enterprise/api/v1/enterprise_catalogs/
#   /enterprise/api/v1/enterprise_catalogs/{uuid}/
#   /enterprise/api/v1/enterprise_catalogs/{uuid}/course_runs/{course_run_id}/
#   /enterprise/api/v1/enterprise_catalogs/{uuid}/courses/{course_key}/
#   /enterprise/api/v1/enterprise_catalogs/{uuid}/programs/{program_uuid}/

apigateway_responses: &apigateway_responses
  default:
    statusCode: "400"
  200:
    statusCode: "200"
  401:
    statusCode: "401"
  403:
    statusCode: "403"
  404:
    statusCode: "404"
  429:
    statusCode: "429"
  500:
    statusCode: "500"

apigateway_responses_with_mapping_template: &apigateway_responses_with_mapping_template
  default:
    statusCode: "400"
  200:
    statusCode: "200"
    responseTemplates:
      # Response body mapping template, this template is used for updating
      # "next" and "previous" urls (both host and url path) while preserving
      # the protocol (http | https) and querystring parameters.
      application/json: >
        #set($inputRoot = $input.path('$'))
        #set($host = $stageVariables.gateway_host)

        #set($URLMatchRegex = "(^https?://)[^/]*[^?]*(.*$)")
        #set($updatedURL = "$1$host$context.resourcePath$2")

        {
          "count": $inputRoot.count,
          "next": "$inputRoot.next.replaceAll($URLMatchRegex, $updatedURL)",
          "previous": "$inputRoot.previous.replaceAll($URLMatchRegex, $updatedURL)",
          "results": $inputRoot.results
        }
  401:
    statusCode: "401"
  403:
    statusCode: "403"
  404:
    statusCode: "404"
  429:
    statusCode: "429"
  500:
    statusCode: "500"

apigateway_responses_with_mapping_template_for_id: &apigateway_responses_with_mapping_template_for_id
  default:
    statusCode: "400"
  200:
    statusCode: "200"
    responseTemplates:
      # Response body mapping template, this template is used for updating
      # "next" and "previous" urls (both host and url path) while preserving
      # the protocol (http | https) and querystring parameters.
      application/json: >
        #set($inputRoot = $input.path('$'))
        #set($host = $stageVariables.gateway_host)
        #set($id = $input.params('id'))

        #set($URLMatchRegex = "(^https?://)[^/]*[^?]*(.*$)")
        #set($updatedURL = "$1$host$context.resourcePath$2")
        #set($resourceIdMatch = "{id}")

        {
          "count": $inputRoot.count,
          "next": "$inputRoot.next.replaceAll($URLMatchRegex, $updatedURL).replace($resourceIdMatch, $id)",
          "previous": "$inputRoot.previous.replaceAll($URLMatchRegex, $updatedURL).replace($resourceIdMatch, $id)",
          "results": $inputRoot.results
        }
  401:
    statusCode: "401"
  403:
    statusCode: "403"
  404:
    statusCode: "404"
  429:
    statusCode: "429"
  500:
    statusCode: "500"

apigateway_responses_with_mapping_template_for_uuid: &apigateway_responses_with_mapping_template_for_uuid
  default:
    statusCode: "400"
  200:
    statusCode: "200"
    responseTemplates:
      # Response body mapping template, this template is used for updating
      # "next" and "previous" urls (both host and url path) while preserving
      # the protocol (http | https) and querystring parameters.
      application/json: >
        #set($inputRoot = $input.path('$'))
        #set($host = $stageVariables.gateway_host)
        #set($uuid = $input.params('uuid'))

        #set($URLMatchRegex = "(^https?://)[^/]*[^?]*(.*$)")
        #set($updatedURL = "$1$host$context.resourcePath$2")
        #set($resourceUuidMatch = "{uuid}")

        {
          "count": $inputRoot.count,
          "next": "$inputRoot.next.replaceAll($URLMatchRegex, $updatedURL).replace($resourceUuidMatch, $uuid)",
          "previous": "$inputRoot.previous.replaceAll($URLMatchRegex, $updatedURL).replace($resourceUuidMatch, $uuid)",
          "results": $inputRoot.results
        }
  401:
    statusCode: "401"
  403:
    statusCode: "403"
  404:
    statusCode: "404"
  429:
    statusCode: "429"
  500:
    statusCode: "500"

responses: &responses
  200:
    description: "OK"
  400:
    description: "Bad Request"
  401:
    description: "Unauthorized"
  403:
    description: "Forbidden"
  404:
    description: "Not Found"
  429:
    description: "Too Many Requests"
  500:
    description: "Internal Server Error"

produces: &produces
  - "application/json"
  - "application/csv"

id_parameter: &id_parameter
  name: "id"
  in: "path"
  required: true
  type: "number"

course_run_id_parameter: &course_run_id_parameter
  name: "course_run_id"
  in: "path"
  required: true
  type: "string"

course_key_parameter: &course_key_parameter
  name: "course_key"
  in: "path"
  required: true
  type: "string"

program_uuid_parameter: &program_uuid_parameter
  name: "program_uuid"
  in: "path"
  required: true
  type: "string"

uuid_parameter: &uuid_parameter
  name: "uuid"
  in: "path"
  required: true
  type: "string"

auth_header: &auth_header
  name: "Authorization"
  in: "header"
  required: true
  type: "string"

limit_qs_parameter: &limit_qs_parameter
  in: "query"
  name: "limit"
  required: false
  type: "number"

offset_qs_parameter: &offset_qs_parameter
  in: "query"
  name: "offset"
  required: false
  type: "number"

page_qs_parameter: &page_qs_parameter
  in: "query"
  name: "page"
  required: false
  type: "number"

page_size_qs_parameter: &page_size_qs_parameter
  in: "query"
  name: "page_size"
  required: false
  type: "number"

# AWS API Gateway vendor extension point. This information is used
#  by https://github.com/awslabs/aws-apigateway-importer.
x-amazon-apigateway-integration-id-response: &apigateway_integration_id
  responses: *apigateway_responses_with_mapping_template_for_id
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.querystring.limit: "method.request.querystring.limit"
    integration.request.querystring.offset: "method.request.querystring.offset"
    integration.request.querystring.page: "method.request.querystring.page"
    integration.request.querystring.page_size: "method.request.querystring.page_size"

x-amazon-apigateway-integration-with-id: &apigateway_integration_with_id_parameter
  responses: *apigateway_responses
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.path.id: "method.request.path.id"

x-amazon-apigateway-integration-with-id-and-querystring-parameters: &apigateway_integration_with_id_and_querystring_parameters
  responses: *apigateway_responses_with_mapping_template_for_id
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.path.id: "method.request.path.id"
    integration.request.querystring.limit: "method.request.querystring.limit"
    integration.request.querystring.offset: "method.request.querystring.offset"
    integration.request.querystring.page: "method.request.querystring.page"
    integration.request.querystring.page_size: "method.request.querystring.page_size"

x-amazon-apigateway-integration-enterprise-customer-catalog-list: &apigateway_integration_enterprise_customer_catalog_list
  responses: *apigateway_responses_with_mapping_template
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.querystring.page: "method.request.querystring.page"
    integration.request.querystring.page_size: "method.request.querystring.page_size"

x-amazon-apigateway-integration-enterprise-customer-catalog-detail: &apigateway_integration_enterprise_customer_catalog_detail
  responses: *apigateway_responses_with_mapping_template_for_uuid
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.path.uuid: "method.request.path.uuid"
    integration.request.querystring.page: "method.request.querystring.page"
    integration.request.querystring.page_size: "method.request.querystring.page_size"

x-amazon-apigateway-integration-with-enterprise-customer-catalog-uuid-and-program-uuid-parameters: &apigateway_integration_with_enterprise_customer_catalog_uuid_and_program_uuid_parameters
  responses: *apigateway_responses
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.path.uuid: "method.request.path.uuid"
    integration.request.path.program_uuid: "method.request.path.program_uuid"
    integration.request.querystring.page: "method.request.querystring.page"
    integration.request.querystring.page_size: "method.request.querystring.page_size"

x-amazon-apigateway-integration-with-enterprise-customer-catalog-uuid-and-course-run-id-parameters: &apigateway_integration_with_enterprise_customer_catalog_uuid_and_course_run_id_parameters
  responses: *apigateway_responses
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.path.uuid: "method.request.path.uuid"
    integration.request.path.course_run_id: "method.request.path.course_run_id"
    integration.request.querystring.page: "method.request.querystring.page"
    integration.request.querystring.page_size: "method.request.querystring.page_size"

x-amazon-apigateway-integration-with-enterprise-customer-catalog-uuid-and-course-key-parameters: &apigateway_integration_with_enterprise_customer_catalog_uuid_and_course_key_parameters
  responses: *apigateway_responses
  httpMethod: "GET"
  type: "http"
  requestParameters:
    integration.request.header.Authorization: "method.request.header.Authorization"
    integration.request.path.uuid: "method.request.path.uuid"
    integration.request.path.course_key: "method.request.path.course_key"
    integration.request.querystring.page: "method.request.querystring.page"
    integration.request.querystring.page_size: "method.request.querystring.page_size"

endpoints:
  v1:

    # /v1/enterprise_catalogs/
    enterpriseCustomerCatalogs:
        get:
          produces: *produces
          parameters:
            - *auth_header
            - *page_qs_parameter
            - *page_size_qs_parameter
          operationId: "get_enterprise_customer_catalogs"
          responses: *responses
          x-amazon-apigateway-integration:
            <<: *apigateway_integration_enterprise_customer_catalog_list
            uri: "https://${stageVariables.enterprise_host}/enterprise/api/v1/enterprise_catalogs/"

    # /v1/enterprise_catalogs/{uuid}/
    enterpriseCustomerCatalogByUuid:
        get:
          produces: *produces
          parameters:
            - *auth_header
            - *uuid_parameter
            - *page_qs_parameter
            - *page_size_qs_parameter
          operationId: "get_enterprise_customer_catalog_by_uuid"
          responses: *responses
          x-amazon-apigateway-integration:
            <<: *apigateway_integration_enterprise_customer_catalog_detail
            uri: "https://${stageVariables.enterprise_host}/enterprise/api/v1/enterprise_catalogs/{uuid}/"

    # /v1/enterprise_catalogs/{uuid}/course_runs/{course_run_id}/
    enterpriseCustomerCatalogCourseRunByUuid:
        get:
          produces: *produces
          parameters:
            - *auth_header
            - *uuid_parameter
            - *course_run_id_parameter
            - *page_qs_parameter
            - *page_size_qs_parameter
          operationId: "get_enterprise_customer_catalog_course_run_by_id"
          responses: *responses
          x-amazon-apigateway-integration:
            <<: *apigateway_integration_with_enterprise_customer_catalog_uuid_and_course_run_id_parameters
            uri: "https://${stageVariables.enterprise_host}/enterprise/api/v1/enterprise_catalogs/{uuid}/course_runs/{course_run_id}/"

    # /v1/enterprise_catalogs/{uuid}/courses/{course_key}/
    enterpriseCustomerCatalogCourseByKey:
        get:
          produces: *produces
          parameters:
            - *auth_header
            - *uuid_parameter
            - *course_key_parameter
            - *page_qs_parameter
            - *page_size_qs_parameter
          operationId: "get_enterprise_customer_catalog_course_by_key"
          responses: *responses
          x-amazon-apigateway-integration:
            <<: *apigateway_integration_with_enterprise_customer_catalog_uuid_and_course_key_parameters
            uri: "https://${stageVariables.enterprise_host}/enterprise/api/v1/enterprise_catalogs/{uuid}/courses/{course_key}/"

    # /v1/enterprise_catalogs/{uuid}/programs/{program_uuid}/
    enterpriseCustomerCatalogProgramByUuid:
        get:
          produces: *produces
          parameters:
            - *auth_header
            - *uuid_parameter
            - *program_uuid_parameter
            - *page_qs_parameter
            - *page_size_qs_parameter
          operationId: "get_enterprise_customer_catalog_program_by_uuid"
          responses: *responses
          x-amazon-apigateway-integration:
            <<: *apigateway_integration_with_enterprise_customer_catalog_uuid_and_program_uuid_parameters
            uri: "https://${stageVariables.enterprise_host}/enterprise/api/v1/enterprise_catalogs/{uuid}/programs/{program_uuid}/"

    # /v1/enterprise-customer/{uuid}/course_enrollments/
    enterpriseCustomerCourseEnrollments:
        post:
          description: "Enrolls users in course runs."
          operationId: "post_enterprise_customer_course_enrollments"
          consumes:
            - "application/json"
          produces:
            - "application/json"
          parameters:
            - *auth_header
            - *uuid_parameter
            - name: "body"
              in: "body"
              description: "List of enrollments to create."
              required: true
              schema:
                type: "array"
                items:
                  type: "object"
                  properties:
                    lms_user_id:
                      description: "The edX user ID."
                      type: "integer"
                    tpa_user_id:
                      description: "The SSO identity provider user ID."
                      type: "string"
                    user_email:
                      description: "A valid email address for the user."
                      type: "string"
                    course_run_id:
                      description: "The course run ID."
                      type: "string"
                      required: true
                    course_mode:
                      description: "The enrollment mode."
                      type: "string"
                      required: true
                    email_students:
                      description: "Email user to notify of enrollment. Defaults to false."
                      type: "boolean"
          responses: *responses
          x-amazon-apigateway-integration:
            responses: *apigateway_responses
            httpMethod: "POST"
            type: "http"
            requestParameters:
              integration.request.header.Authorization: "method.request.header.Authorization"
              integration.request.path.uuid: "method.request.path.uuid"
            uri: "https://${stageVariables.enterprise_host}/enterprise/api/v1/enterprise-customer/{uuid}/course_enrollments/"