API routes (Click a route to expand it, click here to expand/collapse all)
0. Documentation
GET/docs ⎘
Interactive documentation (Swagger UI) of the Supplier, Schema and Consumer APIs.
Response HTTP Type Description
Success 200 string An HTML page.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
    GET/openapi.yaml ⎘
    Provides the OpenAPI 3 specification of the Supplier, Schema and Consumer APIs.
    Response HTTP Type Description
    Success 200 string The OpenAPI 3 specification as YAML.
    MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
    InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
    AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
    UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
    Authentication required:
    No
      1. Supplier API
      GET/schema/{schemaName}.json ⎘
      Provides a json schema based on the name given
      Parameter Location Type Requirements Optional Default value Description
      schemaName URI-Path string
      minLength: 3
      maxLength: 32
      pattern: ^([a-z-_.0-9]+|\*{1})$
      No Name of the schema
      Response HTTP Type Description
      Success 200 string result of the schema json
      MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
      InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
      AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
      UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
      Authentication required:
      No
        POST/supplier/submit ⎘Authentication required
        Transfer any type of predefined message to KATE Innovations Inbound port. Simple authentication is performed using a supplier API-Key.
        Parameter Location Type Requirements Optional Default value Description
        payload POST-body string
        minLength: 1
        maxLength: 4194304
        No Message content
        reference POST-body string
        maxLength: 512
        Yes "" Message reference
        targetCustomer POST-body string
        minLength: 1
        maxLength: 15
        pattern: ^([a-zA-Z0-9-_]+|\*{1})$
        Yes "*" Customer ID of the target (receiver).
        targetDepartment POST-body string
        minLength: 1
        maxLength: 15
        pattern: ^([a-zA-Z0-9-_]+|\*{1})$
        Yes "*" Department ID of the target (receiver).
        waitForProcessing POST-body int
        enum: [ 0, 1 ]
        Yes 0 0/1-bool. If 0, a response is directly returned after validation and before processing and propagation. If 1, the response is returned once all processed messages are delivered to all consumers.
        Response HTTP Type Description
        Success 200 string If "waitForProcessing"=0, always returns a string "Validation passed." on success or one of the listed error codes otherwise. If "waitForProcessing"=1, always returns a string "Delivered: # out of #" on success or one of the listed error codes otherwise.
        InvalidationException 400 Supplier specific invalidation. The message was rejected because it did not pass initial validation. See details for specifics.
        InvalidTargetException 403 Specified target (customer + department) is invalid: it does not exist or you are not authorized (yet) to send to this target.
        MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
        InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
        AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
        UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
        Authentication required:
        Yes
        • Authentication scheme: SupplierAPIKeyAuth Requires: None ⎘
        2. Consumer API
        GET/consumer/poll ⎘Authentication required
        Retrieves any undelivered messages to the Consumer registered to the Consumer API-Key. Simple authentication is performed using a consumer API-Key.
        Parameter Location Type Requirements Optional Default value Description
        limit URI-Query int
        minimum: 1
        maximum: 100
        Yes 10 Maximum amount of messages to return.
        Response HTTP Type Description
        Success 200 ProcessedMessage[] Array of Processed Messages.
        MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
        InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
        AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
        UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
        Authentication required:
        Yes
        • Authentication scheme: ConsumerAPIKeyAuth Requires: None ⎘
        3. Job API
        GET/job/{jobId} ⎘Authentication required
        State of a job and the outcome of every delivery: state, attempts, HTTP status and the response or error of each consumer.
        Parameter Location Type Requirements Optional Default value Description
        jobId URI-Path string
        minLength: 26
        maxLength: 26
        No Job ID as returned by POST /job.
        Response HTTP Type Description
        Success 200 object Job: {jobId, customer, department, state, tsCreated, tsFinished, reference, failureReason, validation, callback: {state, attempts, tsSent, result}, messages: [{id, idArchive, type, tsProcessed, attempts, tsFinished, reference, customer, department, consumer, state, httpStatus, result}]}.
        ModelNotFoundException 404 Instance of this model with provided ID could not be found.
        MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
        InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
        AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
        UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
        Authentication required:
        Yes
        • Authentication scheme: ApiKeyExchangeAuth Requires: 'import:job' ⎘ Arguments:
          #[1]
          { "$object": "KATEv2\\InboundPort\\Authenticators\\JobTenantResolver", "data": [] }
        POST/job ⎘Authentication required
        Submit a message as a job. The API key is exchanged for a token for the given customer/department and the message is validated; an invalid message is refused right away. The job worker then delivers it to all its consumers, and once every delivery is finished the callback receives a POST with JSON {"jobId": "..."}. Use GET /job/{jobId} for the outcome.
        Parameter Location Type Requirements Optional Default value Description
        content POST-body string
        minLength: 1
        maxLength: 4194304
        No Message content (Data Delivery Port V2 / importer format: {"schemaId":"","entities":[...]}). The user is taken from the API key.
        callback POST-body string
        minLength: 1
        maxLength: 1024
        No Public https URL (default port) that receives a POST with JSON {"jobId": "..."} when the job is finished.
        customer POST-body string
        maxLength: 32
        pattern: ^([a-zA-Z0-9-_]*)$
        Yes "" Customer ID to submit for. Optional if the API key has a single (or default) customer/department.
        department POST-body string
        maxLength: 32
        pattern: ^([a-zA-Z0-9-_]*)$
        Yes "" Department ID to submit for. Optional if the API key has a single (or default) customer/department.
        reference POST-body string
        maxLength: 511
        Yes "" Your own reference for this message.
        Response HTTP Type Description
        Success 200 object Object {"jobId": string}.
        InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
        UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
        InvalidationException 400 Supplier specific invalidation. The message was rejected because it did not pass initial validation. See details for specifics.
        InvalidTargetException 403 Specified target (customer + department) is invalid: it does not exist or you are not authorized (yet) to send to this target.
        MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
        AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
        Authentication required:
        Yes
        • Authentication scheme: ApiKeyExchangeAuth Requires: 'import:job' ⎘
        Default APIs
        GET/ ⎘
        Provides the API-specification. Only enabled if API exposure is enabled.
        Parameter Location Type Requirements Optional Default value Description
        format URI-Query string
        enum: [ "KateAPI", "InternalAPIMap", "OpenAPI", "Swagger" ]
        Yes "KateAPI" Documentation format. We support KateAPI documentation, Swagger/OpenAPI documentation and raw output of the internal API-map cache.
        openApiVersion URI-Query int
        enum: [ 2, 3 ]
        Yes 2 Version 3 is crappy with request bodies, so we prefer version 2 (which only sucks regarding Response definitions; hence we prefer KateAPI documentation).
        Response HTTP Type Description
        Success 200 object The API-documentation.
        MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
        InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
        AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
        UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
        Authentication required:
        No
          Management API
          GET/consumer/list ⎘Authentication required
          Lists both active and deactivated consumers.
          Response HTTP Type Description
          Success 200 object Object with 2 keys "active" and "deleted", each containing an array of Consumers.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          GET/supplier/list ⎘Authentication required
          Lists both active and deactivated suppliers.
          Response HTTP Type Description
          Success 200 object Object with 2 keys "active" and "deleted", each containing an array of Suppliers.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          GET/supplier/migration ⎘Authentication required
          Migration state of every active supplier from its legacy key to a KATE API key: linked keyId, whether the legacy key still works, and the customers/departments it delivered for (the grants its API key needs).
          Response HTTP Type Description
          Success 200 array Array of {name, validatorClass, processorClass, keyId, legacyKeyActive, tenants: [{idCustomer, idDepartment, messages, lastReceived}], wildcardMessages}.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: ('kate:admin' OR 'kate:devops') ⎘
          POST/consumer/deactivateByName ⎘Authentication required
          Deactivate a Consumer by provided exact name.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the Consumer to deactivate
          Response HTTP Type Description
          Success 200 object Deactivated Consumer.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidModelOperationException 500 An operation on a model was requested that was not valid/allowed.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          POST/consumer/reactivateByName ⎘Authentication required
          Reactivate a formerly deactivated Consumer by provided exact name.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the deactivated Consumer to reactivate
          Response HTTP Type Description
          Success 200 object Reactivated Consumer.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidModelOperationException 500 An operation on a model was requested that was not valid/allowed.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          POST/mgmt/resumeProcessing ⎘Authentication required
          Resumes any failed/aborted processing of inbound messages of POST /supplier/submit, then does one round of the job worker: process received jobs, deliver due messages (also of /supplier/submit), finish jobs and send their callbacks. The job worker runs from cron by itself; this is for recovery and for environments without it.
          Response HTTP Type Description
          Success 200 object Object with numeric counts: invalidated, processed, delivered, undelivered, jobsFinished, callbacksSent, archived.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          POST/supplier/deactivateByName ⎘Authentication required
          Deactivate a Supplier by provided exact name.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the Supplier to deactivate
          Response HTTP Type Description
          Success 200 object Deactivated Supplier.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidModelOperationException 500 An operation on a model was requested that was not valid/allowed.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: ('kate:admin' OR 'kate:devops') ⎘
          POST/supplier/deleteDeactivatedByName ⎘Authentication required
          Delete a deactivated Supplier by provided exact name.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the deactivated Supplier to delete
          Response HTTP Type Description
          Success 200 true True.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidModelOperationException 500 An operation on a model was requested that was not valid/allowed.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: ('kate:admin' OR 'kate:devops') ⎘
          POST/supplier/linkApiKey ⎘Authentication required
          Links an existing KATE API key to the supplier: jobs (POST /job) of that key are validated and processed as this supplier. Empty keyId unlinks.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the Supplier
          keyId POST-body string
          pattern: ^([0-9A-HJKMNP-TV-Z]{26})?$
          No keyId of the API key (26 chars), or empty to unlink
          Response HTTP Type Description
          Success 200 object Updated Supplier.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          POST/supplier/migrateToApiKey ⎘Authentication required
          Creates a KATE API key for the supplier in the customers service, grants it the customers/departments the supplier delivered for (or the given tenants) and links it to the supplier. The legacy key keeps working until retireLegacyKey. The response contains the plaintext key under "secret"; it is shown only once.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the Supplier
          idUser POST-body int
          minimum: 1
          No User the tokens of the key act as (sub); typically a technical user of the supplier.
          permissions POST-body string
          format: json
          No JSON string[]: permission ceiling of the key, e.g. ["red:import", ...] plus what red-write needs for the imported sets. import:job is always added.
          tokenLifetime POST-body int
          minimum: 60
          maximum: 86400
          Yes 86400 Lifetime in seconds of the tokens; covers the retries of a job.
          tenants POST-body string
          format: json
          Yes null JSON [{idCustomer, idDepartment}] to grant instead of the tenants from the message history.
          Response HTTP Type Description
          Success 200 object {supplier, keyId, secret, grants, failedGrants}.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          DelegatedException 500 Another service invoked by this service using intra-service communication resulted in an error. See details for involved request and resulting error. HTTP status code is dynamically inherited, but defaults to 500.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          POST/supplier/reactivateByName ⎘Authentication required
          Reactivate a formerly deactivated Supplier by provided exact name.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the deactivated Supplier to reactivate
          Response HTTP Type Description
          Success 200 object Reactivated Supplier.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidModelOperationException 500 An operation on a model was requested that was not valid/allowed.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: ('kate:admin' OR 'kate:devops') ⎘
          POST/supplier/retireLegacyKey ⎘Authentication required
          Stops the legacy supplier key from working on POST /supplier/submit, once the supplier uses its KATE API key. Irreversible.
          Parameter Location Type Requirements Optional Default value Description
          name POST-body string No Exact name of the Supplier
          Response HTTP Type Description
          Success 200 object Updated Supplier.
          ModelNotFoundException 404 Instance of this model with provided ID could not be found.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: 'kate:admin' ⎘
          Test API
          POST/test/mapping ⎘Authentication required
          Provide for the payload + the mapping and get the output as json format.
          Parameter Location Type Requirements Optional Default value Description
          payload POST-body string
          format: json
          No The data to map with J2JMapper.
          mapping POST-body string
          format: json
          No The mapping to be used by the J2JMapper.
          Response HTTP Type Description
          Success 200 array The output of the mapping as json.
          MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
          InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
          AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
          UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
          Authentication required:
          Yes
          • Authentication scheme: JWTAuth Requires: None ⎘
          Authentication schemes (Click an authentication scheme to expand it)
          SupplierAPIKeyAuth
          ConsumerAPIKeyAuth
          ApiKeyExchangeAuth
          JWTAuth
          Result wrappers (Click a result-wrapper to expand it)
          Success
          Error