Http Requests

Calling Http services from Blueprint

In order to interact with web services, we have provided a flexible way to send Http requests.

This currently suports:

• String, JSON or Form-typed content

• Custom headers

• Helpers for constructing Urls

• Built-in helpers, allowing you to send requests to the M2 Web Platform

Sending Requests

The basic function for sending Http requests is via the Send Http Request function.

Send Http Request

The parameters are as follows:

Argument	Description
Url	The Url to send the request to. This must be http or https and specified on the Allow list
Verb	Must be one of: GET, POST, PUT, PATCH, DELETE. See Verbs below.
Request Authentication	A built-in authentication method. See Authentication below.
Request Headers	Custom headers to send with the request. See Headers below.
Request Body	The content to send with the request. See Sending Content below.
On Complete	The delegate to fire when the request has completed. See Response Handling below.
Additional Config	Additional configuration settings. See Advanced Configuration below.

The the Send Http Request function has multiple output pins to allow you to determine how to proceed next.

Pin	Description
Request Sent	The request was sent to the remote service. The On Complete delegate will be fired with the results.
Invalid Url	The Url was not valid. It must start with either http or https and be a valid url format
Url Blocked	The Url was not on the Allow list. See Allowed External Urls for guidance.
Invalid Verb	The verb must be one of: GET, POST, PUT, PATCH, DELETE. See Verbs below.
Invalid Content	There was a problem processing the content for sending. See Sending Content below.
Invalid Headers	There was a problem processing the Http Headers to send. See Headers below.
Failed to Send	A problem occurred that meant the request could not be sent. Consult the Unreal log for more information.

Urls

Urls must be either http or https based urls and be present on the Allow list. See Allowed External Urls for guidance.

If you are calling the M2 Web Platform, you can obtain the URL to send to via the helper function.

Urls can be formatted using the Format Url helper.

This will combine the Base Url with the Path, and add on any query parameter pairs (in url encoded format).

Verbs

This function supports the following verbs:

• GET

• POST

• PUT

• DELETE

• PATCH

Other verb will be rejected, with the output Invalid Verb being executed

Authentication

Built-in Authentication

We currently support two primary built-in authentication methods.

• Delegated Token Auth - For providing M2 Platform identity to external services (see Identity Validation)

• M2 Web Platform Auth - For authenticating with the M2 Web Platform itself

Delegated Token Authentication is an async process, as it requires requesting a token from the web platform.

When requesting a token, you will be required to specify the Scope. Doing so adds extra claims to the Delegated Auth Token, so is a useful way of proving to an external service that you have access to a specific M2 World.

It's recommended you use the World scope whenever you can

The type of scopes supported are:

Scope	Description
None	No scoping information is added
Organization	The organization_id claim is added to the token containing the current M2 Organization Id
Project	The organization_id and project_id claims are added; containing the M2 Organization and Project Ids
World	The organization_id, project_id and world_id claims are added; containing the M2 Organization, Project and World Ids
Launch Context	DEPRECATED. Do not use. The organization_id, project_id and launch_context_id claims are added; containing the M2 Organization, Project and Launch Context Ids

M2 Web Platform authentication is used whenever you are making a request to the M2 Web Platform apis.

The simplest node is the Get M2 Web Platform Http Request Auth, which gets the authentication for the first local user. If the code is running on a server, the server's authentication will be used, if on a client then the auth for the first local player will be used.

This is suitable for systems that have no intention of supporting authenticated bot players.

The other methods resolve the authentication from a specific local Morpheus Actor, Morpheus Actor Component or Auth User Context. These methods are preferable if you are using auth from a Morpheus Actor or Morpheus Actor Component (you can use Self as the input), or if you explicitly know the Auth User Context.

It's recommended you use the specific context-based auth nodes where possible, as this allows the system to support Authenticated bots in the future

Headers

Http Headers are used to provide additional metadata to a http server. This can include authentication information, or additional context about the request.

We support two "flavours" of header. Normal, and Sensitive.

Sensitive Headers are used for things like secrets or tokens and are regarded as write-only from blueprint; they cannot be read, inspected or logged.

Other than the flavour of header, the headers are represented by a Map of String / Value pairs that you can specifiy the content of.

Many M2 Web Platform APIs require you yo specify the Organization, Project and/or World context in the form of headers.

Scope	Headers Required
None	N/A
Organization	x-m2-organization-id
Project	x-m2-organization-id x-m2-project-id
World	x-m2-organization-id x-m2-project-id x-m2-world-id
Launch Context (DEPRECATED)	x-m2-organization-id x-m2-project-id x-m2-launch-context-id

You can obtain this information using the helper nodes provided:

You should consult the API Reference to determine which headers to send to the apis.

Sending Content

We support three types of content:

• JSON

• String

• Form

In order to send content you must create it from one of the functions.

JSON Content can be created from either a Json Object or a Json Value (see JSON Handling)

String Content can be created from a String, with an option to specify an explicit content type (by default it uses Content-Type: text/plain.

Form Content will encode a Map of String/String pairs using Url Encoding. Content will be sent using the Content-Type: application/x-www-form-urlencoded.

Advaned Configuration

This is an additional configuration structure that allows you to configure retries and how many redirects the request will follow.

When configuring retries, the request will attempt up to the Max Attempts before failing; it will apply backoffs up to a max backoff interval. We use the "Full Jitter" approach described in by Amazon. This means we have a high amount of randomization in our retries, but will increase the time between attempts.

Response Handling

Once a request has been sent, you need to handle the response.

The response is handled via a custom event. This event has 4 arguments:

Argument	Description
Response Status	An enum to help classify the Response Code
Response Code	The Http Status code from the server. This will be 0 in the case that the request failed to send (eg connection issues, or otherwise)
Response Headers	The Http Headers that were returned by the server
Response Body	The content that the server sent back

Response Status

This is an enum to help classify the Http Response Codes returned. This list is not exhaustive, but covers the main cases that are experienced.

Status	Description
OK	The request was susccessful. Wraps status codes 200 to 206 inclusive.
Not Found	Returned when the server returns a 404
Bad Request	Returned when the server rejects the request with a 400 error
Unauthorized	Returned when the server rejects the request with a 401 error. This usually means you don't have an authentication token or key.
Forbidden	Returned when the server rejects the request with a 403 error. This usually means your authentication credentials are not sufficient.
Connection Failed	Returned when the connection to the server fails.
Transient Error	Wraps a few status codes; typically in the 50x range. These requests are usually safe to retry after a wait.
Not Sent	The request failed to send; this usually happens if the request was internally deferred but was unable to be processed.
Other Error	The request failed but wasn't classified in previous categories. Inspect the Response Code to determine the error.

Response Code

This is the Http Status Code sent by the server. Consult MDN for an exhaustive description of each.

Response Headers

This is a structure that contains a Map of String/Value headers returned from the server.

Response Content

This is the content returned by the server. We support both JSON and String-based content.

The content type can be explicitly determined by using the Get HttpResponse Content Type node.

JSON content can be parsed into either a JSON Object or a JSON Value (see JSON Handling for how to process it). Normally, we check for a well known JSON content type (application/json or text/json) when deserializing the content to JSON. Some services return a non-standard type (eg text/javascript or otherwise) which causes the parsing to fail. If you know the service you're using does this, you can enable Ignore Content Type.

String content is the string content of the request. If you are expecting the content to match a specific content type (eg: application/xml), then you can specify it in the Typed String Content function.

Binary content is not supported at this time; meaning downloading images, videos or other non-text based content will result in unprocessable content.