Experience Endpoints

An Experience Endpoint is a combination of an HTTP method and a route that, when invoked by an HTTP request, can fire an Experience Workflow or directly respond with an Experience Page. Fired workflows can also generate and issue a response to the request.

Endpoint Workflow

Every endpoint can be powered by a Losant Experience Workflow built by you. The workflow is initiated by an Endpoint Trigger Node configured to match your endpoint's method and route. From there, you can use any nodes within the workflow editor to parse your user's request, issue a response using an Endpoint Reply Node, and take auxiliary actions (such as sending data to a third party or issuing alerts via email or SMS).

Viewing Experience Endpoints

Endpoints are versioned resources, so you must first choose one of your Experience Versions. (You may reach your application’s “develop” version by clicking the “Edit” link in the sub-navigation.) After doing so, a list of your Experience Endpoints is accessible in two places:

  • In the left column tree view is a collapsible list of all of the selected version’s endpoints
  • By clicking the “Endpoints” directory within the tree view, you may also view a table of all the version’s endpoints

Experience Endpoints

Select an endpoint in the left column or within the table to view its configuration, make edits, or view workflows and pages associated with the endpoint.

Adding an Experience Endpoint

If you are viewing the “develop” version of your application experience, there are three ways you can add a new experience endpoint:

  • From the version’s overview page, click “Create Endpoint” at the top of the page
  • From the full “Endpoints” list, click the “Add” button in the top right corner of the table
  • From anywhere within the experience version, click the ”+” icon alongside “Endpoints” in the tree view

Endpoint Wizard

After clicking “Create Endpoint” at the top of the page, you will be presented with the Endpoint wizard.

Add Endpoint

This will display a wizard that allows you to create and configure your new endpoint - its method and route, authorization requirements, as well as any new pages or workflows necessary to utilize it - based on how you wish to utilize the endpoint.

Endpoint Wizard

The wizard begins by asking you what sort of endpoint you would like to create:

  • Display an Experience Page: The endpoint’s purpose is to display an Experience Page
  • Return data for an API: The endpoint will be used only to receive and/or return raw data
  • Custom: Skip the wizard and configure the endpoint from scratch

Endpoint Configuration

If you skip the endpoint wizard, or if you return to an endpoint later to edit it, you’ll be taken to a form where all the endpoint’s properties can be defined. Configuring an endpoint takes a few required fields, each of which has its own unique properties.

Method

This is the HTTP method the request should match. It is possible to have one route handle multiple HTTP methods, but each method must be configured as a separate endpoint. Currently, we support these methods:

  • GET requests are typically used for retrieving existing resources. A GET request should be repeatable without changing the state of your application and should return the same response body across requests, assuming the underlying data does not change between requests.
  • POST requests allow for a payload to be sent with the request body. Though POST requests are typically used for creating new resources, they can also be used for complex data queries that require more configuration than can be conveyed in route parameters.
  • PUT requests also allow for a payload body; these requests are typically used to overwrite an existing resource.
  • PATCH requests also allow for a payload body; these requests are typically used to merge changes into an existing resource.
  • DELETE requests should only be used to delete resources from your application.
  • OPTIONS requests are typically sent by web browsers prior to making a cross-origin request. If you have the “Enable Default CORS Settings” box checked in your Experience Settings, it should not be necessary to set up any OPTIONS endpoints. However, you may still create your own OPTIONS routes, and any requests matching those routes will override the default settings handled by Losant.

Endpoint Method and Route

Route

The route is the URL path, or the part after your Experience’s domain. If your Experience’s domain is https://my-custom-slug.onlosant.com, the route is the part that comes after the .com. It always starts with a slash / and may contain a series of static and parameter segments separated by more slashes.

There are a number of rules to consider when building your routes:

  • A single route may only be used once per method. However, a route of /my-route can be set up with a GET method for one endpoint and a POST method for another endpoint, and both are valid.
  • Routes are matched by order of specificity. The more specific a route, the earlier in the process it is checked when a request comes in. The first route that matches the path in the HTTP request will be invoked. Losant takes care of ordering the routes by specificity for you, based on the rules outlined here.
  • Routes can contain string literals, path parameters and wildcards. For example, given the route /devices/{deviceId}/{attribute?}

    • devices is a string literal, which is a static route parameter. String literals always take priority over the other parts of a route, meaning /users/danny will match before /users/{name} if “danny” is included in the name spot.
    • {deviceId} is a required path parameter. If a request is made to /devices/ without a {deviceId} after the trailing slash, the request will fail (unless you have also specified a /devices route matching that method).
    • {attribute?} is an optional path parameter; a request to /devices/123 and /devices/123/temp will both succeed and will both invoke the same endpoint, but the latter will include {"attribute": "temp"} as part of the payload passed to your workflow.
  • Routes must not conflict with each other. The most common example of routes conflicting is with the use of path parameters at the same priority level; for example, a route of /{deviceId} and /{userId} will conflict because, behind the scenes, the router does not know if the value in that part of the path is a device ID or a user ID. For this reason, it is a good idea to start your routes with a descriptive string literal, such as /devices/{deviceId} and /users/{userId}. If you attempt to create a route that conflicts with another route, you will be alerted of the error.
  • Routes can contain wildcards. Wildcards must be used with care, as they will match any request. A typical use case for a wildcard is if you want to create your own OPTIONS endpoint, or a custom 404 Not Found HTTP response; in that case, you would configure a route of /{var*}, where var is available on the payload with the value of whatever the user entered after the first slash in their custom Experience domain.

Access Control

Endpoint access – the ability of a specific user to invoke an endpoint with an HTTP request – can be configured a few different ways …

Endpoint Access Control

  • Any authenticated user endpoints can be invoked by any of your Experience Users when they are signed in. Their authentication token must be included in the request.
  • Only users who are in the following groups… limits access to signed-in users who are a member of any one of the specified Experience Groups. This is useful for building routes that have special privileges (such as resource editing permissions or Experience administration) that you do not want to provide to your normal population of users. To add a group to the endpoint, select the radio button next to the label and begin typing one or more group names into the input.
  • All public users means that anybody, regardless of if they have an Experience User account within your application, no matter if they are currently signed in to their account, can access the endpoint. Public endpoints can be used to allow the retrieval of nonsensitive data; they are also essential to allowing users to sign in to your Experience, as the authentication endpoint must be available to non-signed-in users.

Reply Types

Endpoint Reply Type

Reply Types are static pages or redirects that will be rendered and used to respond to the endpoint. Different reply types can be configured for authenticated and unauthenticated experience users, provided your endpoint’s access control is not set to “All public users”.

Either Reply Type has the following three options:

  • No Static Reply - if the user has access to the endpoint, it will be up to an Experience Workflow to issue a reply. If the user does not have access, the request will fail and a standard response will be issued.
  • Experience Page - the selected static experience page will be rendered and used as the response. The default status code is dependent on whether this is a response to an authorized user or unauthorized user. For authorized users, the default status code is 200, and for unauthorized users the default is 401. However, you can set this to be any valid status code.
  • Redirect - the endpoint will redirect the user to the another URL. The default status code is dependent on whether this is a response to an authorized user or unauthorized user. For authorized users the default status code is 301, and for unauthorized users the default is 302. Redirect Paths are templatable.

Workflows with Endpoint Triggers pointing to this endpoint will still run anytime a request hits the endpoint, If any of those workflows respond with an Endpoint Reply Node, the static reply will take priority over the workflow response.

The following is an example of the context data that you can access in your redirect template or experience page. It is slightly different than the payload passed when rendering in a workflow.

{
  time, // the time of the request
  application, // object containing the application name and ID
  experience: {
    user, // object containing info on the user who made the request (if available)
    endpoint, // object containing info on the endpoint config
    page, // object containing info on the page config
    layout, // object containing info on the layout config,
    version // the experience version for this request
  },
  globals, // key/value mapping of any global variables from the application
  request: {
    path, // the actual request path
    method, // request method (e.g. get, post, patch, delete)
    headers, // object with header names as keys and their values mapped to them
    cookies // object with cookie names as keys and their values mapped to them
  }
}

Other Properties

There are a couple additional properties to set on each endpoint:

Other Endpoint Props

  • Enabled: Whether this endpoint should accept HTTP requests and issue responses. If the endpoint is not enabled, Losant will automatically issue a response of 404 Not Found - {"error": "No endpoint found for route"}.
  • Description: A simple description of the endpoint. This is for internal use only; it will never be visible to Experience Users.

Linked Resources

From an endpoint’s detail page, it is possible to view resources that are related to the endpoint in question by clicking the “Usage” tab at the top of the page.

Endpoint Linked Resources

This will display two resource lists:

  • Workflows that are triggered by requests to this endpoint via an Endpoint Trigger Node.
  • Pages that could potentially be returned by requests to this endpoint. This includes:

    • Static replies, either of the authorized or unauthorized type
    • Endpoint Reply Nodes that respond to the request with a specific Page (those referenced by a payload value are not included here)

Making Endpoint Requests

Using your endpoints is as simple as issuing HTTP requests. When a request is sent to your experience domain or slug

  1. Losant looks up the experience version that is tied to the request.
  2. The request is compared against all endpoints within the experience version and resolves to the first match only.
  3. Given the authorization token included in the request, Losant determines if the user making the request has access to the endpoint.

If the user has access …

  1. If the endpoint has an authorized static reply configured, that static reply will be issued immediately.
  2. Any workflows matching the version will fire any Endpoint Trigger Node that match the HTTP method and route.
  3. If a static reply was not configured for the endpoint, the first Endpoint Reply Node that fired from the workflows will reply to the request. All subsequent replies are ignored.
  4. If no static reply exists, and no workflows fire an Endpoint Reply Node, the request will fail with a generic error.

If the user does not have access …

  1. The endpoint will issue its unauthorized static reply if one has been configured - otherwise, a standard "Unauthorized" response will be issued. In either case, no workflows will fire as a result of the request.

Passing Authorization Tokens

Once you retrieve an authorization token for an Experience User, that token can be appended to any subsequent HTTP requests that require authorization one of three different ways:

  • A query parameter added to the URL (e.g. https://my-custom-slug.onlosant.com/my-user?authorization=[my-token])
  • An Authorization HTTP header with the value Bearer [my-token]
  • A Cookie HTTP header in the format of authorization=[my-token] (you can set a cookie in the user’s browser when they authenticate)

Testing Endpoints

One of the more popular tools for issuing HTTP requests is curl. If you are familiar with curl, chances are you already know how to build requests and test your endpoints.

Postman

If a command line interface isn’t your thing, one of the better (and free) HTTP request builders is Postman. The application includes a GUI for building requests for any HTTP method, sending payload bodies, setting route parameters, defining headers, and everything else you need to test your endpoints.

Experience Workflow Nodes

There are a number of nodes built specifically for working with your Experience Users. Using these nodes, you can …

Handling CORS Requests

Beneath the list of Experience Endpoints is a toggler for enabling default Cross-Origin Resource Sharing settings.

If enabled: OPTIONS requests emitted by web browsers sending asynchronous requests directly to your endpoints will automatically receive an appropriate response.

If disabled: this checkbox will cause asynchronous requests to your endpoints to fail; enabling it is less dangerous, but it would allow cross-origin requests to any endpoint for which you have not set up an OPTIONS route. By default, the checkbox is selected.

Default CORS Setting

The setting is version-specific and, like other experience versioned resources, cannot be changed in any version other than “develop”.

Deleting Endpoints

An endpoint can be deleted by clicking the “Delete” icon next to any endpoint on the list page, or by clicking the “Delete” button in the footer of an endpoint’s edit page.

Delete Endpoint

When deleting an endpoint, you also have the option of deleting any experience workflows triggered by that endpoint. Note that this action deletes any experience workflow with an Endpoint Trigger Node matching this endpoint. If you wish to save your workflows and change out their triggers, or if the workflows are triggered by multiple conditions and you wish to retain them, you should leave this option unchecked.