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/XXXXXX with automatic API logging. The encoded URL is a drop-in replacement for your original URL. Like a bitly link.

The proxy can be handy for monitoring API calls to your APIs or 3rd party APIs for webhooks, Zapier or IFTTT connections, or any other scenario where you can’t easily install an SDK.

Getting started

Encoding a new URL

Sign into your Moesif Dashboard, and go to Top Right Menu -> Installation -> Cloud Proxy. You will see a box to enter your API domain or host.

Encoding URLs for Cloud Proxy

You can encode as many URLs as needed for a particular Moesif org/app such as api1.acmeinc.com and api2.acmeinc.com. All data will be available under the same application in Moesif unless you create a new one.

If you want to isolate data such as development vs production data, create and switch to a new Moesif application first.

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?


Moesif automatically includes the application id (The XXXXXX part) in the URL to identify which application that API data should be logged to. This is the part after the leading / and is stripped off before relaying to the proxied service.

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

If you don’t want the Application Id in the URL or want to set up a white labeled domain via CNAME alias, Moesif supports a X-Moesif-Application-Id header. Instructions can be seen by clicking Advanced: Use HTTP headers instead at bottom of encoding box.

There is no difference between adding a X-Moesif-Application-Id HTTP header vs. having it as the first URL path segment. This enables you to set up a CNAME alias later in your DNS settings that points to the https-api_acmeinc_com-1.moesif.net host.

Modifying your codee

After you have your encoded URL, you can replace any occurrence of your old URL with the newly encoded one.

https://api.acmeinc.com -> https://https-api_acmeinc_com-1.moesif.net/XXXXXX

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/XXXXXX/users/123',

    // replace your api base url with the encoded base url from Moesif
    headers: {
        // 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': '1234',

        // 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/XXXXXX/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:@"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/XXXXXX/users/123")!
// replace your api base url with the encoded base url from Moesif.

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

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/XXXXXX";

  public void sendHttpRequest(String verb, String path) {
      mHeaders.put("X-Moesif-Api-Version", "1.0.1");

      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 option

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 if not part of path

    • value: my_application_id
    • This authenticates/authorizes your application with Moesif.
  • 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.

Limitations of Cloud Proxy

  • The proxied API service has to be accessible from the internet. Meaning the cloud proxy won’t work for http://localhost. You can use any of Moesif’s SDKs if you require capturing API calls behind a firewall.

  • For high volume APIs measured in billions of API calls, Moesif highly recommends using a SDK or API Gateway plugin rather than the cloud proxy for high availability.

  • Certain enterprise features like intelligent sampling are not supported when the cloud proxy is used.

Updated:

Leave a comment