NAV Navbar
  • Overview
  • Mock APIs
  • Endpoints
  • Responses
  • Browser Extension
  • Overview

    Welcome to Pointed! These docs cover:

    If there’s anything we forgot to touch on, hit us up at [email protected].

    Mock APIs

    A mock API is a collection of HTTP endpoints that all live under a root url.

    Example mock API root url: https://13ldskfl23.app.pointed.io

    It might represent an API server that speaks JSON or XML, but it could also just be serving up web pages or static resources. It is kind of like an instantly-available "virtual" backend service.

    Mock APIs can only be interacted with over https.

    Creating a mock API

    To create a mock API, visit the Pointed dashboard and click +. Give the API a name (this is just for your reference) and save it. Boom. It is immediately provisioned under the displayed URL.

    Authentication

    By default, mock APIs are publicly accessible to anyone with the URL. To require authentication to interact with a mock API, toggle the Require authentication? setting on your API’s settings page.

    Then you’ll create an API token and pass it along in requests that interact with the API. If your mock API is configured to require authentication but you do not pass a valid token with a request, Pointed will give back a 403 response with a message asking for a valid token.

    Create a token

    Click the + under API tokens to add a new token.

    Add token to requests

    There are several ways to provide an API token in requests to your mock API. The simplest is to use the browser extension, which will automatically pass the token along. Otherwise you can pass it along as a cookie, a header, or a query parameter.

    All three methods achieve the same thing.

    Set a cookie with the name mockApiToken.

    curl "https://my-cool-api-url.app.pointed.io"
      -H "Cookie: mockApiToken=my-cool-api-token"
    

    Query parameter

    Set a query parameter with the name mock_api_token.

    curl "https://my-cool-api-url.app.pointed.io?mock_api_token=my-cool-api-token"
    

    Request header

    Set an HTTP request header with the name x-mock-api-token.

    curl "https://my-cool-api-url.app.pointed.io"
      -H "x-mock-api-token: my-cool-api-token"
    

    Simulating latency

    You can apply a fixed amount of latency across the whole API to simulate slow responses by configuring the Delay all responses by ___ section of the API settings. You can also do this on a per-endpoint basis.

    Endpoints

    An endpoint belongs to a mock API. It consists of an HTTP request method (like GET) and a path (like /derp). When an HTTP request is made to an endpoint, it gives back a fixed or dynamic response. Navigate to a mock API in the Pointed dashboard to view and interact with its endpoints.

    Create an endpoint

    Navigate to a mock API in the Pointed dashboard and under Endpoints click + to create a new HTTP endpoint. Give it an HTTP request method and a path. See examples for path options.

    To interact with your endpoint, you’ll make an HTTP request with the appropriate method (a.k.a. verb) to https://my-cool-api.app.pointed.io/my-cool-path.

    Example static path.

    /dogs
    

    Example dynamic path with named url parameters. The value of :id will be available to the response definition.

    /dogs/:id/dog-deets
    

    Example dynamic path with wildcard segment. The value of *stuff will be available to the response definition.

    /dogs/*stuff
    

    The previous path definition will match any of the following URLs:

    /dogs/cool
    /dogs/cool/some/long/path
    

    And a wildcard segment doesn’t have to be at the end. Again the value of *stuff will be available to the response definition.

    /dogs/*stuff/woof
    

    The previous path definition will match any of the following URLs:

    /dogs/cool/woof
    /dogs/cool/some/long/path/woof
    

    Simulating latency

    You can apply a fixed amount of latency on a per-endpoint basis to simulate slow responses by configuring the Delay all responses by ___ section of the endpoint settings.

    Responses

    A response is made up of three things:

    There are two ways to define responses for a given endpoint: a set of canned responses via the user interface with one of them being the default, and straight JavaScript to do basically whatever the bleep you want based on various aspects of the request.

    Either way, the Big Idea is: define all the responses that your app needs to know how to handle. Then go through and toggle them (either manually or programmatically) to see how your app handles each response.

    UI

    This is the way to define responses with no coding required. It’s not quite as flexible as defining responses via JavaScript.

    After navigating to the settings page for a particular endpoint, ensure that UI is selected under Define responses via... and then click + under Responses to define one or more responses via a form. Check Make this response the default to set the default upon creation, or click the thumbs-up icon on any response to set that one to the default.

    When defining the response body, you can access the following dynamic elements of the request using handlebars syntax.

    Example response body accessing dynamic values by name

    {
      id: {{request.path_parameters.id}},
      date: {{request.query_params.date}},
      sweet: true,
      {{request.cookies.what}}: 'ever',
      the_request_auth_header_thing: {{request.headers.x-auth-token-thing}}
    }
    

    If you’ve defined more than one response, the default response will be returned unless you provide an x-mock-api-response-id header along with the request, setting its value to the id of the response you’d like.

    curl "https://my-cool-api-url.app.pointed.io"
      -H "x-mock-api-response-id: derp1derp2derp3"
    

    To find the response id, navigate to editing the response, and grab the id out of the url.

    JavaScript

    After navigating to the settings page for a particular endpoint, ensure that Straight JavaScript is selected under Define responses via....

    A code editor appears. It contains a JavaScript function that receives an object representing the request, and returns an object representing the response. Cool!

    So here again you have access to headers, path params, query params, request params, and cookies. Unlike the UI definition, you can also dynamically determine the status code and headers. Also, of course, this is JavaScript so you can do whatever else to dynamically build the response.

    The second argument to the function is an instance of faker so you can generate random data in your response.

    /**
     * Function that takes request data and returns a 
     * standard response object. This code is run in a 
     * sandboxed Node environment. You can’t use
     * require() cause, yeah.
     *
     * @param {Object} request
     * @param {Object} request.headers
     * @param {Object} request.pathParams
     * @param {Object} request.queryParams
     * @param {Object} request.requestParams
     * @param {Object} request.cookies
     * @param {Object} faker Fake data generator 
     *                 github.com/marak/Faker.js
     *
     * @return {Object} response
     * @return {Object} response.headers
     * @return {Number} response.status
     * @return {String} response.body
     */
    module.exports = function(request, faker) {
      return {
        headers: {
          'content-type': 'text/plain'
        },
        status: 200,
        body: 'cool fake paragraph: ' + faker.lorem.paragraph()
      };
    }
    

    Browser Extension

    Installation

    Install the Pointed Proxy Chrome Extension here.

    When you open your browser’s developer tools there will be a new Pointed Proxy tab.

    Usage

    The browser extension lets you define proxy rules that tell your browser to proxy/redirect certain HTTP requests to a Pointed mock API. This allows you to integrate with a mock API without changing your application’s code.

    Proxy rules

    Proxy rules define which HTTP requests to match, and to where they should be proxied. A proxy rule is made up of four parts:


    Example proxy rule #1

    # With the following proxy rule in place:
    request method: *
    request url: https://api.dogs.com/*
    mock api base url: https://13ldskfl23.app.pointed.io
    
    # The following browser requests are proxied accordingly:
    POST https://api.dogs.com 
    -> POST https://13ldskfl23.app.pointed.io
    
    GET https://api.dogs.com/dogs/123/details 
    -> GET https://13ldskfl23.app.pointed.io/dogs/123/details
    
    GET https://what.api.dogs.com/dogs/123/details 
    -> not proxied 
    

    Example proxy rule #2

    # With the following proxy rule in place:
    request method: GET 
    request url: https://api.dogs.com/dog-foods/:id
    mock api base url: https://13ldskfl23.app.pointed.io
    
    # The following browser requests are proxied accordingly:
    GET https://api.dogs.com/dog-foods/abc123 
    -> GET https://13ldskfl23.app.pointed.io/dog-foods/abc123
    
    PUT https://api.dogs.com/dog-foods/abc123
    -> not proxied 
    

    Working with proxy rules

    After opening your browser’s developer tools and clicking the Pointed Proxy tab, you can create/edit/delete/disable/enable proxy rules via UI.

    Check out the examples to get an idea of the effect of different proxy rules.