Remove proxy interfaces RAML (not implemented) OKAPI-542

#%RAML 0.8
title: Okapi Core API
version: 2.0
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - InterfaceDescriptor: !include InterfaceDescriptor.json
  - InterfaceList: !include InterfaceList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json
  - Permission: !include Permission.json
  - PullDescriptor: !include PullDescriptor.json

/_/deployment/modules:
  description: Deployment service. This is responsible for starting and
    stopping modules.
  post:
    description: Deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor.
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing

  /{instance_id}:
    get:
      description: Retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: shutdown instance
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/discovery/modules:
  description: Discovery service. This is responsible for monitoring
    all instances (deployed) on, possibly many, deployment nodes.
  post:
    description: Register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Return all instances
    responses:
      200:
        description: Ok
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: List all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      put:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      delete:
        description: Remove registration for a given instance
        responses:
          204:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          404:
            description: Not Found
            body:
              text/plain:
/_/discovery/health:
  description: Health service for individual instances
  get:
    description: Get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: Health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
/_/discovery/nodes:
  description: Get information about nodes
  get:
    description: Get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{node_id}:
    put:
      description: Update descriptor of a particular node, only the name can be changed
      body:
        application/json:
          schema: NodeDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: NodeDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    get:
      description: Get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:

/_/proxy/modules:
  description: Proxy modules service
  post:
    description: Announce new module to the proxy. Once successful a module
      can be selected for a specific tenant.
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all or subset of modules for proxy
    queryParameters:
      filter:
        description: Filter by module ID
        type: string
        required: false
      full:
        description: whether full or compact MD should be returned
        type: boolean
        required: false
      orderBy:
        description: Order by field
        type: string
        required: false
      order:
        description: Order
        enum: [desc, asc]
        required: false
      preRelease:
        description: whether to include modules with pre-release info
        type: boolean
        required: false
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{module_id}:
    get:
      description: Retrieve descriptor for a particular module
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: Update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
    delete:
      description: Remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/proxy/tenants:
  description: Tenants service
  post:
    description: Create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: Tenant has been created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created tenant
        body:
          application/json:
            schema: TenantDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: List all tenants
    responses:
      200:
        description: List of tenants in a brief format
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: Retrieve a tenant
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: Update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: Remove a tenant
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        403:
          description: Forbidden
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    /modules:
      post:
        description: Enable a module for tenant. Only the member 'id' from
          TenantModuleDescriptor is used in this operation.
          This call will eventually be replaced by the 'install' service.
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          201:
            description: Created
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
              Location:
                description: URI to the enabled module
            body:
              application/json:
                schema: TenantModuleDescriptor
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      get:
        description: Get enabled modules for tenant
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      /{module_id}:
        description: CRUD service for getting module and upgrading module
          for a tenant.
        get:
          description: Look up particular module selection
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        post:
          description: Upgrade a module for a tenant. Enable new module and
            disable current module with new module ID in body and existing ID
            in path.
            This call will eventually be replaced by the 'install' service.
          body:
            application/json:
              schema: TenantModuleDescriptor
          responses:
            201:
              description: Created
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
                Location:
                  description: URI to the enabled module
              body:
                application/json:
                  schema: TenantModuleDescriptor
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server Error
              body:
                text/plain:
        delete:
          description: Disable a module for a tenant.
            This call will eventually be replaced by the 'install' service.
          responses:
            204:
              description: Gone
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
            400:
              description: Client Error
              body:
                text/plain:
    /install:
      post:
        description: Enable, disable or upgrade one or more modules for
          tenant. The request body and response body is of the same type
          TenantModuleDescriptorList. This list includes one or more
          modules to be enabled, disabled or upgraded. The request is the
          initial desired changes and the response is the list of changes
          that must be fulfilled to satisfy dependencies.
          This service will eventually partially replace
          /_/proxy/tenants/{tenant}/modules . It also allows
          enabling multiple modules in in one transaction.
          For simulate=true, the response, can be viewed as a recipe for what
          must be deployed (optionally) and enabled/disabled by the existing
          tenants-modules CRUD service.
        queryParameters:
          deploy:
            description: whether to deploy (or undeploy if disabling)
            type: boolean
            required: false
          simulate:
            description: Whether the installation is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        body:
          application/json:
            schema: TenantModuleDescriptorList
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /upgrade:
      post:
        description: Check if newer modules of exist and upgrade for tenant.
          The response is a list of modules that should be enabled, disabled
          or upgraded to perform the upgrade.
        queryParameters:
          deploy:
            description: whether to deploy (or undeploy if disabling)
            type: boolean
            required: false
          simulate:
            description: whether the upgrade is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /interfaces:
      get:
        description: Get all interfaces for tenant
        queryParameters:
          full:
            description: whether brief or full interface list
            type: boolean
            required: false
          type:
            description: limit by interfaceType
            type: string
            required: false
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: InterfaceList
          400:
            description: Client Error
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      /{interface_id}:
        get:
          description: Get all modules that provide the specified interface ID
          queryParameters:
            type:
              description: limit by interfaceType
              type: string
              required: false
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptorList
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server error
              body:
                text/plain:
/_/proxy/health:
  description: Check health of modules
  get:
    description: Check health of modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      500:
        description: Server Error

/_/proxy/pull/modules:
  description: Pull module descriptors from a remote repository
  post:
    description: Pull modules (i.e. Module Descriptors) from a remote
      repository. The PullDescriptor includes one or more URLs. And
      the operation will try all URLs in order until one succeeds. Hence,
      the URLs should be pointing to identical remote repositories.
    body:
      application/json:
        schema: PullDescriptor
    responses:
      200:
        description: OK
        headers:
          Location:
            description:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/env:
  description: Environment service. Environment variables are system
    variables that allows us to configure modules in a uniform way.
    They can hold fundamental database configuration, etc.
  post:
    description: Add environment entry
    body:
      application/json:
        schema: EnvEntry
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the environment entry instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: EnvEntry
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Get list of all environment variables
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: Get info for one environment variable
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: Remove environment variable
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/version:
  description: Service for getting information about Okapi
  get:
    description: get Okapi version
    responses:
      200:
        description: OK, with version in body
        body:
          text/plain:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/invoke/tenant/{id}:
  description: Call module with Tenant ID in path. This
    service offers support for systems that need to "call-back" Okapi and
    don't allow setting the Tenant ID in the HTTP header.
  get:
    description: Invoke any service (the rest of the path, any method,
      any response).
    responses:
      200:
        description: OK
        body:
          text/plain:

#TODO implement single module health check

#%RAML 0.8
title: Okapi Core API
version: 2.0
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - InterfaceDescriptor: !include InterfaceDescriptor.json
  - InterfaceList: !include InterfaceList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json
  - Permission: !include Permission.json
  - PullDescriptor: !include PullDescriptor.json

/_/deployment/modules:
  description: Deployment service. This is responsible for starting and
    stopping modules.
  post:
    description: Deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor.
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing

  /{instance_id}:
    get:
      description: Retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: shutdown instance
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/discovery/modules:
  description: Discovery service. This is responsible for monitoring
    all instances (deployed) on, possibly many, deployment nodes.
  post:
    description: Register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Return all instances
    responses:
      200:
        description: Ok
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: List all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      put:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      delete:
        description: Remove registration for a given instance
        responses:
          204:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          404:
            description: Not Found
            body:
              text/plain:
/_/discovery/health:
  description: Health service for individual instances
  get:
    description: Get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: Health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
/_/discovery/nodes:
  description: Get information about nodes
  get:
    description: Get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{node_id}:
    put:
      description: Update descriptor of a particular node, only the name can be changed
      body:
        application/json:
          schema: NodeDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: NodeDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    get:
      description: Get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:

/_/proxy/modules:
  description: Proxy modules service
  post:
    description: Announce new module to the proxy. Once successful a module
      can be selected for a specific tenant.
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all or subset of modules for proxy
    queryParameters:
      filter:
        description: Filter by module ID
        type: string
        required: false
      full:
        description: whether full or compact MD should be returned
        type: boolean
        required: false
      orderBy:
        description: Order by field
        type: string
        required: false
      order:
        description: Order
        enum: [desc, asc]
        required: false
      preRelease:
        description: whether to include modules with pre-release info
        type: boolean
        required: false
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{module_id}:
    get:
      description: Retrieve descriptor for a particular module
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: Update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
    delete:
      description: Remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/proxy/interfaces:
  description: Module Interface definitions
  post:
    description: Announce new interface to the proxy. Once successful,
      ModuleDescriptors can provide the interface, without specifying details
    body:
      application/json:
        schema: InterfaceDescriptor
    responses:
      201:
        description: Created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: InterfaceDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all known interfaces
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: InterfaceList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{interface_id}:
    get:
      description: Retrieve descriptor for a particular interface
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: InterfaceDescriptor
    put:
      description: Update descriptor of a particular interface
      body:
        application/json:
          schema: InterfaceDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: InterfaceDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
    delete:
      description: Remove interface
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/proxy/tenants:
  description: Tenants service
  post:
    description: Create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: Tenant has been created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created tenant
        body:
          application/json:
            schema: TenantDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: List all tenants
    responses:
      200:
        description: List of tenants in a brief format
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: Retrieve a tenant
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: Update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: Remove a tenant
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        403:
          description: Forbidden
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    /modules:
      post:
        description: Enable a module for tenant. Only the member 'id' from
          TenantModuleDescriptor is used in this operation.
          This call will eventually be replaced by the 'install' service.
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          201:
            description: Created
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
              Location:
                description: URI to the enabled module
            body:
              application/json:
                schema: TenantModuleDescriptor
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      get:
        description: Get enabled modules for tenant
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      /{module_id}:
        description: CRUD service for getting module and upgrading module
          for a tenant.
        get:
          description: Look up particular module selection
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        post:
          description: Upgrade a module for a tenant. Enable new module and
            disable current module with new module ID in body and existing ID
            in path.
            This call will eventually be replaced by the 'install' service.
          body:
            application/json:
              schema: TenantModuleDescriptor
          responses:
            201:
              description: Created
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
                Location:
                  description: URI to the enabled module
              body:
                application/json:
                  schema: TenantModuleDescriptor
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server Error
              body:
                text/plain:
        delete:
          description: Disable a module for a tenant.
            This call will eventually be replaced by the 'install' service.
          responses:
            204:
              description: Gone
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
            400:
              description: Client Error
              body:
                text/plain:
    /install:
      post:
        description: Enable, disable or upgrade one or more modules for
          tenant. The request body and response body is of the same type
          TenantModuleDescriptorList. This list includes one or more
          modules to be enabled, disabled or upgraded. The request is the
          initial desired changes and the response is the list of changes
          that must be fulfilled to satisfy dependencies.
          This service will eventually partially replace
          /_/proxy/tenants/{tenant}/modules . It also allows
          enabling multiple modules in in one transaction.
          For simulate=true, the response, can be viewed as a recipe for what
          must be deployed (optionally) and enabled/disabled by the existing
          tenants-modules CRUD service.
        queryParameters:
          deploy:
            description: whether to deploy (or undeploy if disabling)
            type: boolean
            required: false
          simulate:
            description: Whether the installation is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        body:
          application/json:
            schema: TenantModuleDescriptorList
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /upgrade:
      post:
        description: Check if newer modules of exist and upgrade for tenant.
          The response is a list of modules that should be enabled, disabled
          or upgraded to perform the upgrade.
        queryParameters:
          deploy:
            description: whether to deploy (or undeploy if disabling)
            type: boolean
            required: false
          simulate:
            description: whether the upgrade is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /interfaces:
      get:
        description: Get all interfaces for tenant
        queryParameters:
          full:
            description: whether brief or full interface list
            type: boolean
            required: false
          type:
            description: limit by interfaceType
            type: string
            required: false
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: InterfaceList
          400:
            description: Client Error
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      /{interface_id}:
        get:
          description: Get all modules that provide the specified interface ID
          queryParameters:
            type:
              description: limit by interfaceType
              type: string
              required: false
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptorList
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server error
              body:
                text/plain:
/_/proxy/health:
  description: Check health of modules
  get:
    description: Check health of modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      500:
        description: Server Error

/_/proxy/pull/modules:
  description: Pull module descriptors from a remote repository
  post:
    description: Pull modules (i.e. Module Descriptors) from a remote
      repository. The PullDescriptor includes one or more URLs. And
      the operation will try all URLs in order until one succeeds. Hence,
      the URLs should be pointing to identical remote repositories.
    body:
      application/json:
        schema: PullDescriptor
    responses:
      200:
        description: OK
        headers:
          Location:
            description:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/env:
  description: Environment service. Environment variables are system
    variables that allows us to configure modules in a uniform way.
    They can hold fundamental database configuration, etc.
  post:
    description: Add environment entry
    body:
      application/json:
        schema: EnvEntry
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the environment entry instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: EnvEntry
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Get list of all environment variables
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: Get info for one environment variable
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: Remove environment variable
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/version:
  description: Service for getting information about Okapi
  get:
    description: get Okapi version
    responses:
      200:
        description: OK, with version in body
        body:
          text/plain:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/invoke/tenant/{id}:
  description: Call module with Tenant ID in path. This
    service offers support for systems that need to "call-back" Okapi and
    don't allow setting the Tenant ID in the HTTP header.
  get:
    description: Invoke any service (the rest of the path, any method,
      any response).
    responses:
      200:
        description: OK
        body:
          text/plain:

#TODO implement single module health check


Align Tracking header levels and order

Align Tracking header levels and order

#%RAML 1.0
---
title: Tracking API
version: v2
baseUri: https://tracking.bring.com/api
types:
  Consignment:
    type: object
    properties:
      consignmentSet:
        type: ConsignmentSet
      apiVersion:
        type: ApiVersion
  ConsignmentSet:
    type: object
    description: ?
    properties:
      consignmentId:
        type: string
      previousConsignmentId:
        type: string
        required: false
      packageSet:
        type: Package[]
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
        required: false
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
        required: false
      senderLogo:
        type: string
        required: false
      totalListPrice:
        type: string
        required: false
      totalContractPrice:
        type: string
        required: false
      listPricePackageCount:
        type: string
        required: false
      contractPricePackageCount:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  Package:
    type: object
    properties:
      statusDescription:
        type: string
      descriptions:
        type: string[]
        required: false
      packageNumber:
        type: string
      previousPackageNumber:
        type: string
      productName:
        type: string
      productCode:
        type: string
      productLink:
        type: string
        required: false
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      listPrice:
        type: string
        required: false
      contractPrice:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      pickupCode:
        type: string
        required: false
      shelfNumber:
        type: string
        required: false
      dateOfReturn:
        type: string
        required: false
      dateOfEstimatedDelivery:
        type: string
        required: false
      dateOfDelivery:
        type: string
        required: false
      senderName:
        type: string
        required: false
      senderAddress:
        type: Address
        required: false
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: AdditionalService[]
        required: false
      requestPackage:
        type: requestedPackageType
        required: false
  Event:
    type: object
    properties:
      description:
        type: string
      status:
        type: string
      lmEventCode:
        type: string
        required: false
      recipientSignature:
        type: recipientSignatureType
      unitId:
        type: string
      unitInformationUrl:
        type: string
        required: false
      unitType:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
      gpsXCoordinate:
        type: string
        required: false
      gpsYCoordinate:
        type: string
        required: false
      gpsMapUrl:
        type: string
        required: false
  Address:
    type: object
    properties:
      addressLine1:
        type: string
      addressLine2:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
  requestedPackageType:
      type: object
      properties:
        userEmail:
          type: string
        requestedPackageOn:
          type: string
        caseId:
          type: string
        hasBeenRequested:
          type: string
  AdditionalService:
    type: object
    properties:
      id:
        type: string
      description:
        type: string
      amount:
        type: string
      currencyCode:
        type: string
      longDescription:
        type: string
        required: false
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  recipientSignatureType:
    type: object
    properties:
      name:
        type: string
      linkToImage:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        type: string
        required: false

documentation:
- title: Introduction
  content: |
      The Tracking API provides the opportunity to track shipments by reference, package or shipment number.
      It is an easy way to display details and the status of shipments.
      The information available in this API is the same that is publically available from the [Tracking web site](http://tracking.bring.com/).

- title: Versioning
  content: |
    Latest Tracking API version: `v2`

    We encourage you to use the latest version of our API all time.  Of course, we keep the previous version for some time so that you will get enough time to convert your application. This API supports versioning by two means.

    - **Select version by request-header**
      Use the normal URL but add the following request-header:

      | Header | Example |
      |:-------|:--------|
      | `api-version` | `2` |

      **Example request**
      ```curl -H "api-version: 2" https://tracking.bring.com/api/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

    - **Select version by URL**
      Use the normal URL, but add **```{v1, v2}```** to the URL. Example:

      | Application | URL example |
      |:-------|:--------|
      | Open tracking | https://tracking.bring.com/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |
      | Logged-in tracking | https://api.bring.com/tracking/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |

      You can verify that your request were used correctly by certifying that the response contains an element based on the request type:

      | URI request | Response type | Example |
      |:-------|:--------|:--------|
      | tracking.json | `application/json; charset=utf-8` | `{"apiVersion": "2"}` |
      | tracking.xml | `application/xml;charset=utf-8` | `<ApiVersion>2</ApiVersion>` |

      **Example request**
      ```curl -v https://tracking.bring.com/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

- title: Authentication
  content: |
    If you have a Mybring user, you can log in to the Tracking API. Authenticated requests have the following benefits:

    - More information about parcels:
      - Prices
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/` | A URL that sort of identifies where you're using the APIs. |

    The above headers must be present whilst using our logged-in variant of the tracking api. Also, you will have to use the endpoint: [https://api.bring.com/tracking/api/](https://api.bring.com/tracking/api/)

- title: Formats
  content: |
    The Tracking API generates the following formats:
    - ```XML```
    - ```JSON```
    - ```JSONP```

- title: JSON API
  content: |
      We follow the [JSON API](http://jsonapi.org/) specification with one
      exception: we allow media type to be specified as `application/json`
      instead of `application/vnd.api+json`.

/{version}/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  description: Get information about an existing shipment based on a tracking number, shipment number or reference.
  uriParameters:
    version:
      enum: [ v1, v2 ]
      description: v1 is deprecated and will be removed soon. Use v2 when requesting the tracking API
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      X-Bring-Client-URL:
        description: A URL that sort of identifies where you're using the APIs.
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT, 370000000000000001
      aktornummer:
        description: Represents a valid customer number registered with Posten
        type: string
        required: false
        example: "12345678901"
      callback:
        description: JSONP callback function name
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        description: |
          For testing you can use "TESTPACKAGE-AT-PICKUPPOINT" as the tracking number to generate test results. For real tracking this must be a valid number.

          You can find an XSD for the XML response here: [tracking-v2.xsd](https://tracking.bring.com/schema/api/tracking-v2.xsd).

          A parcel has a number of events connected to it during its travel. Here are a list of current event statuses that can be returned.

          | Event | Description |
          |:-------|:--------|
          | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading. |
          | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
          | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
          | `CUSTOMS` | Package is in customs clearance. |
          | `COLLECTED` | The parcel has been collected at pickup address. |
          | `DELIVERED` | Package has been delivered. |
          | `DELIVERED_SENDER` | Package has been returned to the sender |
          | `DELIVERY_CANCELLED` | Home delivery has been canceled by the customer. |
          | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
          | `DELIVERY_ORDERED` | Home delivery has been ordered |
          | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
          | `HANDED_IN` | Package has been handed in to Bring. |
          | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country. |
          | `IN_TRANSIT` | Package is in transit. |
          | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
          | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
          | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
          | `RETURN` | The package has been returned to sender. |
          | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
          | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |
          | `UNKNOWN` | Represents unknown / undefined events |

        body:
          application/json:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below shows an successful deliverance of a package at a pickup point
                value: !include examples/successful.json
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.json
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.json
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.json
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.json
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.json
          application/xml:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/successful.xml
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.xml
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.xml
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.xml
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.xml
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.xml

#%RAML 1.0
---
title: Tracking API
version: v2
baseUri: https://tracking.bring.com/api
types:
  Consignment:
    type: object
    properties:
      consignmentSet:
        type: ConsignmentSet
      apiVersion:
        type: ApiVersion
  ConsignmentSet:
    type: object
    description: ?
    properties:
      consignmentId:
        type: string
      previousConsignmentId:
        type: string
        required: false
      packageSet:
        type: Package[]
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
        required: false
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
        required: false
      senderLogo:
        type: string
        required: false
      totalListPrice:
        type: string
        required: false
      totalContractPrice:
        type: string
        required: false
      listPricePackageCount:
        type: string
        required: false
      contractPricePackageCount:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  Package:
    type: object
    properties:
      statusDescription:
        type: string
      descriptions:
        type: string[]
        required: false
      packageNumber:
        type: string
      previousPackageNumber:
        type: string
      productName:
        type: string
      productCode:
        type: string
      productLink:
        type: string
        required: false
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      listPrice:
        type: string
        required: false
      contractPrice:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      pickupCode:
        type: string
        required: false
      shelfNumber:
        type: string
        required: false
      dateOfReturn:
        type: string
        required: false
      dateOfEstimatedDelivery:
        type: string
        required: false
      dateOfDelivery:
        type: string
        required: false
      senderName:
        type: string
        required: false
      senderAddress:
        type: Address
        required: false
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: AdditionalService[]
        required: false
      requestPackage:
        type: requestedPackageType
        required: false
  Event:
    type: object
    properties:
      description:
        type: string
      status:
        type: string
      lmEventCode:
        type: string
        required: false
      recipientSignature:
        type: recipientSignatureType
      unitId:
        type: string
      unitInformationUrl:
        type: string
        required: false
      unitType:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
      gpsXCoordinate:
        type: string
        required: false
      gpsYCoordinate:
        type: string
        required: false
      gpsMapUrl:
        type: string
        required: false
  Address:
    type: object
    properties:
      addressLine1:
        type: string
      addressLine2:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
  requestedPackageType:
      type: object
      properties:
        userEmail:
          type: string
        requestedPackageOn:
          type: string
        caseId:
          type: string
        hasBeenRequested:
          type: string
  AdditionalService:
    type: object
    properties:
      id:
        type: string
      description:
        type: string
      amount:
        type: string
      currencyCode:
        type: string
      longDescription:
        type: string
        required: false
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  recipientSignatureType:
    type: object
    properties:
      name:
        type: string
      linkToImage:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        type: string
        required: false

documentation:
- title: Introduction
  content: |
      The Tracking API provides the opportunity to track shipments by reference, package or shipment number.
      It is an easy way to display details and the status of shipments.
      The information available in this API is the same that is publically available from the [Tracking web site](http://tracking.bring.com/).

- title: Formats
  content: |
    The Tracking API generates the following formats:
    - ```XML```
    - ```JSON```
    - ```JSONP```
- title: Versioning
  content: |
    Latest Tracking API version: `v2`

    We encourage you to use the latest version of our API all time.  Of course, we keep the previous version for some time so that you will get enough time to convert your application. This API supports versioning by two means.

    - **Select version by request-header**
      Use the normal URL but add the following request-header:

      | Header | Example |
      |:-------|:--------|
      | `api-version` | `2` |

      **Example request**
      ```curl -H "api-version: 2" https://tracking.bring.com/api/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

    - **Select version by URL**
      Use the normal URL, but add **```{v1, v2}```** to the URL. Example:

      | Application | URL example |
      |:-------|:--------|
      | Open tracking | https://tracking.bring.com/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |
      | Logged-in tracking | https://api.bring.com/tracking/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |

      You can verify that your request were used correctly by certifying that the response contains an element based on the request type:

      | URI request | Response type | Example |
      |:-------|:--------|:--------|
      | tracking.json | `application/json; charset=utf-8` | `{"apiVersion": "2"}` |
      | tracking.xml | `application/xml;charset=utf-8` | `<ApiVersion>2</ApiVersion>` |

      **Example request**
      ```curl -v https://tracking.bring.com/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

- title: Authentication
  content: |
    If you have a Mybring user, you can log in to the Tracking API. Authenticated requests have the following benefits:

    - More information about parcels:
      - Prices
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/` | A URL that sort of identifies where you're using the APIs. |

    The above headers must be present whilst using our logged-in variant of the tracking api. Also, you will have to use the endpoint:

        https://api.bring.com/tracking/api/
- title: JSON API
  content: |
      We follow the [JSON API](http://jsonapi.org/) specification with one
      exception: we allow media type to be specified as `application/json`
      instead of `application/vnd.api+json`.

/{version}/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  description: Get information about an existing shipment based on a tracking number, shipment number or reference.
  uriParameters:
    version:
      enum: [ v1, v2 ]
      description: v1 is deprecated and will be removed soon. Use v2 when requesting the tracking API
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      X-Bring-Client-URL:
        description: A URL that sort of identifies where you're using the APIs.
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT, 370000000000000001
      aktornummer:
        description: Represents a valid customer number registered with Posten
        type: string
        required: false
        example: "12345678901"
      callback:
        description: JSONP callback function name
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        description: |
          For testing you can use "TESTPACKAGE-AT-PICKUPPOINT" as the tracking number to generate test results. For real tracking this must be a valid number.

          You can find an XSD for the XML response here: [tracking-v2.xsd](https://tracking.bring.com/schema/api/tracking-v2.xsd).

          A parcel has a number of events connected to it during its travel. Here are a list of current event statuses that can be returned.

          | Event | Description |
          |:-------|:--------|
          | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.
 |
          | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
          | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
          | `CUSTOMS` | Package is in customs clearance. |
          | `COLLECTED` | The parcel has been collected at pickup address. |
          | `DELIVERED` | Package has been delivered. |
          | `DELIVERED_SENDER` | Package has been returned to the sender |
          | `DELIVERY_CANCELLED` | Home delivery has been canceled by the customer. |
          | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
          | `DELIVERY_ORDERED` | Home delivery has been ordered |
          | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
          | `HANDED_IN` | Package has been handed in to Bring. |
          | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country.
 |
          | `IN_TRANSIT` | Package is in transit. |
          | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
          | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
          | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
          | `RETURN` | The package has been returned to sender.
 |
          | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
          | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |
          | `UNKNOWN` | Represents unknown / undefined events |

        body:
          application/json:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below shows an successful deliverance of a package at a pickup point
                value: !include examples/successful.json
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.json
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.json
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.json
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.json
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.json
          application/xml:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/successful.xml
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.xml
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.xml
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.xml
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.xml
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.xml