Contract

  • Updated on Jan 24, 2022
  • Published on Dec 4, 2020
  • 5 minute(s) read
Prev Next

The capability Asynchronous Request-Response Management is for managing the asynchronous version of the integration pattern request-response, see Wikipedia

The capability must be implemented with an at-least-once delivery guarantee. There should also be mechanisms for minimizing the risk of delivering a message more than once, i.e. duplicated requests, as described more in detail below.

Create request

This method must store the information about the request internally and return an id that will serve as the clients ticket for this request. The capability must eventually send the request to the server and make the response available to the client.

POST /Requests
{
    "Method" : {Method},
    "Url" : {Url},
    "Headers": {Headers},
    "Content": {Content},
    "ContentType": {ContentType},
    "Metadata": {
        "SendBefore": {SendBefore}
        "SendBefore": {SendAfter}
        "Priority": {Priority},
        "Callback": {
            "Url": {CallbackUrl},
            "Headers": {CallbackHeaders},
            "Context": {CallbackContext}
        },
        "Authentication": {
            "Context": {AuthenticationContext},
            "IsAnonymous": bool // If true, AM dispatcher need not fetch auth from Originator
        },
    },
}
200 OK
{RequestId}

Parameters

Mandatory fields are marked with an asterisk.

The body consists of an HttpRequest object with the following attributes. :

Field Type Description
*Method string The HTTP Request Method name (case insensitive), e.g. "POST".
*Url string The complete URL for the request, e.g. "https://example.com/api/Persons".
Headers object The HTTP headers for the request as a HashMap, i.e. key-value-pairs with the name of the header as the key and the value is either a single header value or an array of header values.
Name string A name for the request. Not necessarily unique.
Content string The content of the HTTP request, serialized to a string.
ContentType string The HTTP content type, e.g. "application/json".
*Metadata object Additional information about the request. Never null.
*Metadata.Priority float The assigned priority of the request. The value should be in the interval [0.0, 1.0], i.e. a number >= 0.0 and <= 1.0. A higher value has higher priority than a lower value.
Metadata.SendBefore string The expiration time for the request. Formatted according to the ISO-8601 standard.
Metadata.ActivationTime string The earliest time the request can be sent. Formatted according to the ISO-8601 standard. Null if the request should be sent as soon as possible.
Metadata.Callback object Information about if and where we should send a callback to the client when the final response is available.
Metadata.Callback.Url string The URL where the response will be posted.
Metadata.Callback.Headers string The HTTP headers for the request as a HashMap, i.e. key-value-pairs with the name of the header as the key and the value is either a single header value or an array of header values.
Metadata.Callback.Context string
/// Serialized version of a context that will be supplied with the callback.
Metadata.Authentication object When using Authentication Refreshing, a Context can be provided that will be used when calling the TokenUrl for renewing the authentication credentials. See Seeding configurations and"Refreshing authentication" below for API Contract of TokenUrl
Metadata.Authentication.IsAnonymous boolean In case the request can be made without an Authorization header, this will prevent Async Manager from trying to fetching new authentication credentials

Response

The HTTP status code should be 200 OK.

Field Type Description
RequestId string The id for the handling of this request. The client can use it to reference this request.

Exceptions

Http Status Code Description
400 Bad request The request could not be accepted, the response content contains the details.

Examples

POST /Requests
{
    "Method" : "GET",
    "Url" : "http://example.com/Persons/23",
    "Headers" : 
        {
            "Correlation-Id" : "768b5a12-a030-421f-98d5-a7036a48336d",
            "Accept" : ["appliction/json", "application/xml"]
        },
    "Content": null,
    "Metadata": {
        "ActivationTime": null
        "Priority": 0.5,
        "Callback" : null
    },
}
200 OK
"52109bcf-5aba-431c-86b4-7bd43ab3e0cf"


Read response

The HTTP status code should be 200 OK.

This method must return the response that is associated with the request id. If the response is not yet available, the method must indicate that the client should try again later.

GET /Requests/{id}/Response
GET /Responses
200 OK
{
    "Id": {RequestId}
    "HttpStatus": {HttpStatus},
    "Content": {Content},
    "Headers": {Headers},
    "Exception": {
        "Name": {Name}
        "Message": {Message}
    },
    "Metadata" : {
        "Executions" : {Executions}
        "RequestHasCompleted" : {RequestHasCompleted}
        "CompletionReason" : {CompletionReason},
        "RecommendedWaitTimeInSeconds": {RecommendedWaitTimeInSeconds}
    }
}

Parameters

Mandatory fields are marked with an asterisk.

Field Type Description
id string The request id that was received when the Create request method was called.

Response

The HTTP status code is 200 OK. If the specified request id can't be found, there will be a null response.

Field Type Description
Id int The request id.
HttpStatus int The HTTP status for the latest call response. null if no response yet or if the latest response was an exception.
Content string The content of the latest HTTP response, serialized to a string.
Headers Object The HTTP headers from the latest response, serialized into a JSON object.
Exception Object If the latest response was an exception, then this is information about that exception.
Exception.Name string The name of the exception. Never null or empty.
Exception.Message string A description of the exception. Never null or empty.
Metadata object Additional information about the response. Never null.
Metadata.Executions int The number of times that the request has been executed.
Metadata.RequestHasCompleted boolean True if the request has completed and we have a final response.
Metadata.CompletionReason string Describing the reason why a request was considered to be complete.
Metadata.RecommendedWaitingTimeInSeconds float If the final response isn't available, this is the recommended time to wait before asking again.

Exceptions

Http Status Code Description
400 Bad request The request id was not found, the content contains the details.

Examples

GET /Requests/52109bcf-5aba-431c-86b4-7bd43ab3e0cf/Response
200 OK
{
    "Id": "52109bcf-5aba-431c-86b4-7bd43ab3e0cf",
    "HttpStatus" : 0,
    "Headers" : null,
    "Content": null,
    "Exception": {
        "Name": "HttpOperationException",
        "Message": "The operation timed out after 100 seconds."
    }
    "Metadata" : {
        "HasCompleted" : false
        "Executions" : 1,
        "RecommendedWaitTimeInSeconds": 60
    }
}

GET /Requests/52109bcf-5aba-431c-86b4-7bd43ab3e0cf/Response
200 OK
{
    "Id": "52109bcf-5aba-431c-86b4-7bd43ab3e0cf",
    "Status" : 200,
    "Headers" : 
        {
            "Correlation-Id" : "768b5a12-a030-421f-98d5-a7036a48336d",
        },
    "Content": "{  \"Name\" :  \"John Doe\" }",
    "Exception" : null,
    "Metadata" : {
        "HasCompleted" : true
        "NumberOfExecutions" : 2,
        "RecommendedWaitTimeInSeconds": 0
    }
}

GET /Requests/this-is-an-unkown-request-id/Response
200 OK
null

Refreshing authentication

If you configure Async Manager with the Authentication section, you will be able to refresh authentication for requests where auth has expired (or was missing, if you don't wish to have the JWTs stored in the blobs.

When refreshing authentication, Async Manager will make a POST to the configured TokenUrl for the orginating client:

POST https://orginator.com/path/to/refreshing/token
Authorization: "{JWT aquired for calling the originating client}"

{
    "ExpiredAuthorizationHeader": "Bearer ey... | Basic 898aeff3 | ...",
    "AuthenticationContext": "{The value of Metadata.Authentication.Context from the request}"
}

200 OK
{
    "Headers": [
        { "Name": "Authorization", "Value": [ "Bearer ey..." ] },
        // ...
    ]
}
Field Description
ExpiredAuthorizationHeader The Authorizationheader that was used to to make the request, but it was expired or got a 401 response. Note: Could be null if no Authorization header was used on the initial request.
AuthenticationContext The value from the property Metadata.Authentication.Context from the request. Can be used to provide information about what type of authentication to respond with
Headers The response is expected to be a list of header values that will be used to make the request