Integration Guide - Cloud Proxy

The cloud proxy works by encoding your API host like https://api.acmeinc.com to a new URL like https://https-api_acmeinc_com-1.moesif.net with automatic monitoring. The encoded URL is a drop-in replacement for your original URL.

The proxy can be very handy for monitoring outgoing API calls to 3rd parties, for monitoring webhooks, or any other environments where you can’t install any libs.

Getting started

1. Authenticating with Moesif

Create an app and get your Application Id by, going to your Moesif Dashboard -> Top Right Menu -> App Setup -> Cloud Proxy. You can create multiple apps like production or development. Add the Application Id to your HTTP requests using the HTTP request header:

X-Moesif-Application-Id: Your Application Id

Can't use HTTP headers?


If you cannot add request HTTP headers such as in certain CRM and marketing automation tools, you can insert the Application Id as the first URL path segment. Thus, if your Moesif Application Id is XXXXXX, then an example URL might look like

https://https-api_acmeinc_com-1.moesif.net/XXXXXX?&take=10

There is no difference between adding a X-Moesif-Application-Id HTTP header vs. inserting it as the first URL path segment.

2. Creating proxied URL

After you have your Application Id, you can enter a API base URL to be encoded such as https://api.example.com. Moesif will generate an encoded url like:

https://https-api_acmeinc_com-1.moesif.net

This moesif.net URL is a drop-in replacement for your old API base URL and can be used anywhere the old URL was used. If you don’t want a moesif.net domain and want it white labeled, you can always set up a CNAME alias later in your DNS settings that points to the moesif.net URL.

Example Code

Javascript

// Example client code calling your backend RESTful API through our proxy

var request = require('request');

var options = {

    method: 'GET',

    url: 'https://https-api_acmeinc_com-1.moesif.net/users/123',

    // replace your api base url with the encoded base url from Moesif
    headers: {
        // set the token for all API calls to identify your app with Moesif
        'X-Moesif-Application-Id': '',

        // Session token used for authentication/authorization, could be a JWT, Device Identifier, etc
        'X-Moesif-Session-Token': '',

        // The persistence user_id of the end user
        'X-Moesif-User-Id': '',

        // Tag  API Call as getting a user profile if to /users
        'X-Moesif-Tags': url.contains('user') && method.contains('GET') ? 'user' : ''
    }
};

function callback(error, response, body) {
    // your code
}

request(options, callback);

Objective-C

// Example client code calling your backend RESTful API through our proxy

NSURL *url = [NSURL URLWithString: @"https://https-api_acmeinc_com-1.moesif.net/users/123"];
// replace your api base url with the encoded base url from Moesif.

NSMutableURLRequest *request=[NSMutableURLRequest requestWithURL:url
                               cachePolicy:NSURLRequestReloadIgnoringCacheData
                               timeoutInterval:60];

[request setHTTPMethod:@"GET"];

[request setValue:@"" forHTTPHeaderField:@"X-Moesif-Application-Id"];
// set the token for all API calls to identify your app to Moseif.  

[request setValue:@"user" forHTTPHeaderField:@"X-Moesif-Tags"];
// only set the user tag for the key API endpoint for user data.

Swift

// Example client code calling your backend RESTful API through our proxy

let url: NSURL = NSURL(string: "https://https-api_acmeinc_com-1.moesif.net/users/123")!
// replace your api base url with the encoded base url from Moesif.

request = NSMutableURLRequest(URL:url)
request.HTTPMethod = "GET"

request.addValue("", forHTTPHeaderField: "X-Moesif-Application-Id")
// set the token for all API calls to identify your app to Moseif.

request.addValue("user", forHTTPHeaderField: "X-Moesif-Tags")
// only set the user tag for the key API endpoint for user data.

Java

// Example client code calling your backend RESTful API through our proxy

  private Map<String, String> mHeaders = new HashMap<String, String>();

  private static final String sBaseUrl = "https://https-api_acmeinc_com-1.moesif.net";

  public void sendHttpRequest(String verb, String path) {
      mHeaders.put("X-Moesif-Api-Version", "1.0.1");
      mHeaders.put("X-Moesif-Application-Id", "X");
      // set the token for all API calls to identify your app to Moseif.

      if (verb.equals("GET") && path.startsWith("/user")) {
          mHeaders.put("X-Moesif-Tags", "user");
          // only set the user tag for the key API endpoint for user data.
      }
      String userId = getUserSession().getUserId();
      if (!Strings.isNullOrEmpty(userId)) {
          mHeaders.put("X-Moesif-User-Id", userId);
      }

      String url = sBaseUrl + path;

      // do HTTP request
  }

HTTP header options

The only required header is the application_id which identifies your app with Moesif.

We use variety of pattern recognition techniques, it can detect quite well. With additional headers, Moesif becomes more accurate. We highly recommend tag at least one of your API end points as where your app ‘user’ metadata is contained the response body such as GET /users/me

  • X-Moesif-Application-Id required

    • value: my_application_id
    • This authenticates/authorizes your application with Moesif.
    • If you cannot add HTTP headers, alternatively, you can add the Application Id as the first URL path segment.
  • X-Moesif-Tags recommend

    • value: Comma Separated list of tags for the API Call
      1. user
        • The user tag is a hint to what is considered the “user profile” for the signed in end user.
        • Add to a single method/endpoint template which you consider has the most user metadata.
        • For example, if you have an endpoint that gets the authenticated user via GET /users/me, add this header to those API Calls. The verb or url doesn’t matter but the response body should have user’s data.
        • You shouldn’t add to more than one method/endpoint combination. i.e. Don’t add it to both GET /users and POST /users unless both return the same JSON schema.
  • X-Moesif-Api-Version optional

    • value: X.X.X
    • Not required, but you can tag this API with a version. Any string is fine such as semantic versioning.
  • X-Moesif-User-Id optional

    • value: user_id string from your app
    • We attempt to figure out what your end user’s user_id is automatically, If Moesif has trouble, you can override it by setting it manually. It is recommended to set the Moesif User-Id field with the id used in your own databases and services.
  • X-Moesif-Session-Token optional

    • value: your end user’s session token
    • Again, we automatically figure out what is your end user’s session token, and fall back to IP Address if can’t be found. You are free to override this if unhappy with the results. Session Token can be a short lived token.

Moesif uses the session token to help distribute your org’s traffic. If the detected session token is a low cardinality key such as the server IP address instead of end user’s client IP or auth token, then you may want to override the session token to be something that is higher in cardinality.

  • X-Moesif-Request-Masks optional

    • value: key1,key2,key3
    • This header is a comma separated list of keys in the request body that you want to be masked (i.e. hidden from Moesif) such as for privacy or compliance reasons.
    • Moesif supports automatic masking of both XML and JSON content types. Other types may require custom logic in your application.
    • For each key, we’ll recursively find all fields in the request body’s JSON with that key, and override any values with an x, so they won’t be stored or analyzed in anyway.
    • For example, if the key is password, then if request body’s JSON has password as a key for any of the fields or its sub-objects, it will be masked. Masking is done before any persistence including temporally persistent queues like Kafka.
    • To simplify your code, it is ok to add this header in all your API requests even if the key is absent, null value, or a GET request with no request body.
  • X-Moesif-Response-Masks optional

    • value: key1,key2,key3
    • This header is a comma separated list of keys in the response XML or JSON body that you want to be masked (i.e. hidden from Moesif)
    • Similar to the X-Moesif-Request-Masks header, except this header is for the response body.

Updated: