api-compact.yaml

# License Manager 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
# POST  /api/v1/subscriptions/{uuid}/licenses/assign/
# POST  /api/v1/subscriptions/{uuid}/licenses/bulk-revoke/
# POST  /api/v1/bulk-license-enrollment

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

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

bulk_revoke_apigateway_responses: &bulk_revoke_apigateway_responses
  default:
    statusCode: "400"
  204:
    statusCode: "204"
  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"
  201:
    description: "Created"
  400:
    description: "Bad Request"
  401:
    description: "Unauthorized"
  403:
    description: "Forbidden"
  404:
    description: "Not Found"
  423:
    description: "Locked"
  429:
    description: "Too Many Requests"
  500:
    description: "Internal Server Error"

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

bulk_revoke_responses: &bulk_revoke_responses
  204:
    description: "No Content - All revocations were successful"
  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"

enterprise_customer_uuid_qs_param: &enterprise_customer_uuid_qs_param
  in: "query"
  name: "enterprise_customer_uuid"
  required: true
  type: "string"

enterprise_customer_uuid_qs_param_optional: &enterprise_customer_uuid_qs_param_optional
  in: "query"
  name: "enterprise_customer_uuid"
  required: false
  type: "string"

enroll_all_qs_param: &enroll_all_qs_param
  in: "query"
  name: "enroll_all"
  required: false
  type: "string"

subscription_uuid_qs_param: &subscription_uuid_qs_param
  in: "query"
  name: "subscription_uuid"
  required: false
  type: "string"


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

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

endpoints:
  v1:
    # api/v1/subscriptions/{uuid}/licenses/assign/
    assignLicenses:
      post:
        description: "Assigns a license to given user emails and sends an activation email."
        operationId: "assign_licenses"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - *uuid
          - name: "data"
            in: "body"
            description: "User emails, sfids, and email content."
            required: true
            schema:
              type: "array"
              items:
                type: "object"
                properties:
                  user_emails:
                    description: "List of emails to assign licenses."
                    type: "array"
                    required: true
                    items:
                      type: "string"
                      description: "user email"
                  user_sfids:
                    description: "List of salesforce user ids to assign licenses."
                    type: "array"
                    items:
                      type: "string"
                      description: "user's salesforce opportunity id"
                  greeting:
                    description: "Email template closing e.g Hello."
                    type: "string"
                  closing:
                    description: "Email template closing e.g Goodbye."
                    type: "string"
                  notify_users:
                    description: "Send license assignment email or not."
                    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.license_manager_host}/api/v1/subscriptions/{uuid}/licenses/assign/"
    # /api/v1/subscriptions/{uuid}/licenses/bulk-revoke/
    revokeLicenses:
      post:
        description: "Revokes one or more licenses in a subscription plan"
        operationId: "revoke_licenses"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - *uuid
          - name: "RequestPayload"
            in: "body"
            description: "User emails OR search filters for emails and status"
            required: true
            schema:
              type: "array"
              items:
                $ref: "#/definitions/RequestPayload"
        responses: *bulk_revoke_responses
        x-amazon-apigateway-integration:
          responses: *bulk_revoke_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.license_manager_host}/api/v1/subscriptions/{uuid}/licenses/bulk-revoke/"
    # /api/v1/bulk-license-enrollment
    bulkLicenseEnrollment:
      post:
        description: "Enrolls a list of learners in a given list of courses after verifying license subsidies."
        operationId: "bulk_license_enrollment"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - *enterprise_customer_uuid_qs_param
          - *enroll_all_qs_param
          - *subscription_uuid_qs_param
          - name: "payload"
            in: "body"
            description: "User emails and course run keys along with a notify learners flag"
            required: true
            schema:
              type: "array"
              items:
                type: "object"
                properties:
                  emails:
                    description: "list of learner emails"
                    type: "array"
                    required: true
                    items:
                      type: "string"
                      description: "user email"
                  course_run_keys:
                    description: "list of courses to enroll learners into"
                    type: "array"
                    required: true
                    items:
                      type: "string"
                      description: "course run key"
                  notify:
                    description: "Whether to notify learner of their enrollment"
                    type: "boolean"
                    required: true
        responses: *responses
        x-amazon-apigateway-integration:
          responses: *apigateway_responses
          httpMethod: "POST"
          type: "http"
          requestParameters:
            integration.request.header.Authorization: "method.request.header.Authorization"
            integration.request.querystring.enterprise_customer_uuid: "method.request.querystring.enterprise_customer_uuid"
            integration.request.querystring.enroll_all: "method.request.querystring.enroll_all"
            integration.request.querystring.subscription_uuid: "method.request.querystring.subscription_uuid"
          uri: "https://${stageVariables.license_manager_host}/api/v1/bulk-license-enrollment"
    # /api/v1/subscriptions
    subscriptionsList:
      get:
        operationId: subscriptions_summary_endpoint
        description: Returns a list of subscription plans for a customer
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - *enterprise_customer_uuid_qs_param_optional
          - name: "page"
            in: "query"
            required: false
            type: "integer"
          - name: "current"
            in: "query"
            required: false
            type: "string"
        responses: *get_responses
        x-amazon-apigateway-integration:
          responses: *apigateway_get_responses
          httpMethod: "GET"
          type: "http"
          requestParameters:
            integration.request.header.Authorization: "method.request.header.Authorization"
            integration.request.querystring.enterprise_customer_uuid: "method.request.querystring.enterprise_customer_uuid"
            integration.request.querystring.page: "method.request.querystring.page"
            integration.request.querystring.current: "method.request.querystring.current"
          uri: "https://${stageVariables.license_manager_host}/api/v1/subscriptions/"

definitions:
  BulkRevokeFilters:
    type: "object"
    properties:
      user_email:
        type: "string"
        description: "User email filter"
      status_in:
        type: "array"
        description: "Array of valid license statuses"
        items:
          type: "string"
          description: "status of the license"
    description: "Values provided to perform filtering against."
  RequestPayload:
    type: "object"
    properties:
      user_emails:
        type: "array"
        description: "List of emails with which licenses are associated"
        items:
          type: "string"
          description: "user email"
      filters:
        type: "array"
        description: "Filters for lookup and filtering of licenses to revoke."
        items:
          $ref: "#/definitions/BulkRevokeFilters"