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.
The parameters are as follows:
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.
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:
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.
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:
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.
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.
Last updated
Was this helpful?