๐Ÿ’ Web Services

Invoking Json Web Services from MSquared

Http Json Nodes

There are several Http nodes available for use that allow you to make JSON requests to APIs.

The following Blueprint Nodes are available for use:

  • Http Get Json

  • Http Post Json

  • Http Put Json

  • Http Patch Json

  • Http Delete

All nodes have the following common pins:

  • Url: The target url you are sending the Http request to

  • Auth Context: The local Morpheus Actor/Morpheus Actor Component you wish to use to authenticate the request

And the following output pins are common:

  • On Success: Control flow invoked when the request completed successfully (usually a 200 Status Code)

  • On Fail: Control flow invoked when the request failed.

  • Status Code: The Http Status code of the response. If this is zero, we usually had a problem sending the request.

  • Json Response: A Json Object Structure of the data that was returned. This is only valid upon success, and if the API returned JSON data.

If you expand the node's properties, you get access to more advanced options:

  • Headers: A String-String Map of additional headers to add to the request

  • Scope: Adds any MSquared scoping headers

  • Include Delegated Auth Token: See Authentication

Http Get Json

This node issues a simple GET request to a Url and parses the result as JSON.

Http Post/Put/Patch Json

These nodes are used to send data to an url as JSON.

They each have a "Json" input pin that accepts a Json Object Structure. For more detail about how to use this see the Worked Example page.

If the API returns a JSON response it will be present on the Json Response pin.

Http Delete

This node issues a DELETE request to the url. It it not normal for a response to be returned.

Urls

A url can be either a full https url for an external site or a path to target an MSquared Web Platform API.

Authentication

When you provide an Auth Context to any of the nodes, you are providing a hint that the request requires authentication.

MSquared API Requests

If your request is targeting an MSquared Web Platform API you will need to provide a reference to a Morpheus Actor / Morpheus Actor Component that you have local authority over. In the majority of cases, this will be a "self" reference if you are using this as part of a Morpheus Actor Component Blueprint.

It's important to note that you cannot use this to impersonate another user as either a client or a server.

External APIs

If you are calling your own API you can require that a Delegated Auth Token is provided with the request. This token allows your external service to validate the identity of the caller as an MSquared user.

See the section on Validating Identity for more information.

Custom Authentication

If you need to use a custom authentication scheme, such as Basic auth or provide your own credentials. You can do this by adding your own headers to the request.

To do this, you will need to make a Map of String/String and populate it with your own header values. Typically, you would use the key of Authorization for auth headers. The credentials you provide will depend completely on the api you are calling.

Be careful about embedding credentials into Blueprints as they will be available to anyone with your content. Storing your own credentials securely is out of scope of this tutorial.

Scoping

If you add a Scope option the nodes will apply HTTP headers allow you to identify the current context in which the metaverse is running.

If you need to know this, it is recommended that you select the World scope, as it contains the most useful information.

The following additional headers are added to the request:

ScopeHeadersDescription

None

N/A

No extra headers are applied

Organization

x-m2-organization-id

Applies the current Organization Id of the Metaverse

Project

x-m2-organization-id

x-m2-project-id

Applies the current Organization Id and Project Id of the Metaverse

World

x-m2-organization-id

x-m2-project-id

x-m2-world-id

Applies the current Organization Id, Project Id and World Id of the Metaverse

Launch Context

x-m2-organization-id

x-m2-project-id

x-m2-launch-context-id

Deprecated Applies the current Organization Id, Project Id and Launch Context Id of the Metaverse

Last updated