Add Car Sales Data to your App Without Changing Your Backend (Or Even Having A Backend)

With the introduction of our SubUser API Keys it is now possible to use data from the CIS Automotive API in an application as simple as a single HTML document with no backend required. We wanted to make it easy to use our data in applications that don't follow the traditional client server architecture.

We put together a Dashboard Demo that showcases how to use some of our endpoints from a static HTML page with no backend.

Previously this type of application would have required some backend infrastructure to query our API, manage sessions, and manage/ cache requests. With the SubUser API Keys this burden is offloaded from your backend onto our infrastructure which simplifies application development and improves time to market.

General Workflow

Create an account and pick a subscription plan.
Create some SubUser API Keys and embed them in your javascript application or website.
Make some requests and start working with our automotive market data.

Creating Our SubUser API Keys

Section Highlights

SubUser API Keys are not available when accessing our API through a thrid party provider. You must have an account with us if you want to use SubUser Keys in your application.
Make a request to the /makeSubUserKey endpoint and specify the domain of your site and endpoints you want the key to have access to. You can pick any endpoints that require a JWT (JSON Web Token) as an argument and all calls are billed at your normal rate for the endpoint's tier.
Example.com and www.example.com are two different domains. Keys made for one domain will not work on the other. Example.com/foo and example.com/bar are the same domain and can both use the same SubUser Key.
Keys for example.com will not work on 'localhost' and vice versa. We recomend you create a SubUser Key for 'localhost' for testing and development of your application, but keys for 'localhost' should never be shared or published in your application.
You can view your issued SubUser Keys and metadata by calling the /getSubUserKeys endpoint.
You can revoke a SubUser Key at any time by calling the /revokeSubUserKey endpoint and providing the key's UUID.
Users on a basic plan can only make SubUser Keys for 'localhost'. If you want to add our data to your site you need a higher tier plan.
Our javascript library is available via Jsdelivr's CDN minified and non minified

Show full text

When you create a SubUser API Key you specify the domain allowed to make the requests and the endpoints the SubUser Key is allowed to access. Users with a paid plan can specify any domain they'd like, but users on a free or basic plan may only make keys for 'localhost'.

You can create a SubUser API Key programatically by making a POST request to our /makeSubUserKey endpoint or you can manually create one on the docs page. You will need to specify the domain the key will be used on, but be aware that example.com and www.example.com are two different domains and the key for one will not work on the other . If your users can access your application via either domain, then create two keys (one for each domain) and have some javascript on the page determine which domain was loaded and pick the corresponding key. You should also make at least one SubUser Key with the domain of 'localhost' for building and testing your application. A SubUser Key with a different domain will not work on 'localhost'.

In addition to the domain you will also need to pick the endpoints the SubUser Key will be able to access. You should only pick endpoints you intend to use in your application to help reduce the potential for misuse. By default the "endPoints" argument is ["*"] which means all endpoints. At time of writing there is a visual bug in the openAPI documentation renderer that causes the "endPoints" argument for the /makeSubUserKey endpoint to render as ["string"]. This is a visual bug only and is interpreted by our API as ["*"] meaning all endpoints. You can also see the default value by clicking on the schema next to it.

When you create a SubUser key the "token" value returned is used to access the endpoints you specified as the "jwt" value in the request. This "token" is valid until revoked and can only be used for requests to the specified endpoints from the specified domain. If you ever need to retrieve the value of a SubUser API Key you can make a request to the /getSubUserKeys endpoint to see all SubUser Keys you've created and their associated metadata. You can revoke a SubUser Key with a call to the /revokeSubUserKey endpoint with the key's specified UUID.

Setup Your Template

Once you have your SubUser API Key you can just embed it in your html document. We have a skeleton template below taken from our dashboard demo that uses Vue.js to populate a dropdown and perform an action. We use AJAX and callbacks to populate the skeleton with data and our cisapi library provides javascript bindings for our API.

HTML


<!DOCTYPE html>
<html lang="en">
    <head></head>
    <body>
        <div id="main">
            <label class="">Pick A Region</label>
            <v-select :options="regions" @click="pickRegion(option)" v-model="activeRegion">
                <template v-slot:option="option">
                    ${ option.label }
                </template>
            </v-select>
            <p>Your selected region is ${activeRegion}</p>
        </div>
        <div style="display:none" id="cisapi-jwt">YOUR_SUBUSER_API_KEY_HERE</div>
        <!--Our CISAPI Library requires jquery to make ajax calls.
            This example uses Vue.js and Vue-Select for DOM manipulation, 
            but is not a requirement for our library.-->
        <script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
        <script src="https://unpkg.com/vue-select@latest"></script>
        <script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.js"></script>
        <script src="https://cdn.jsdelivr.net/gh/cisapi/cis-api-js/cisapi.min.js"></script>
        <script src="/myVueApp.js"></script>
    </body>
</html>

myVueApp.js

Vue.component('v-select', VueSelect.VueSelect);

var app = new Vue(
    {
        el: "#main",
        delimiters: ['${', '}'],
        data: {           
            regions: [],
            activeRegion: "",
        },
        watch: {
            activeRegion: function (newRegion, oldRegion) {
                if (newRegion === oldRegion) {
                    return;
                }
                this.activeRegion = newRegion;
                this.pickRegion(null);
            } 
        },
        methods: {
            init: function () {
                this.getRegions();
            },
            getRegions: function () {
                cisapi.getRegions(this.getRegionsSuccess, this.getRegionsFailure);
            },
            getRegionsSuccess: function (data) {
                this.regions = data["data"];
                if (this.regions.length > 0) {
                    this.activeRegion = this.regions[0];
                }
            },
            getRegionsFailure: function (data) {},
            pickRegion: function (regionName) {
                if (regionName != null) {
                    this.activeRegion = regionName;
                }
                //#Take additional region specific
                //#logic here
            }
        }
    });
app.init();

Conclusion

Our SubUser API Keys help make our automotive data available and convient to use for applications that don't follow the traditional client server architecture. When we designed the SubUser Keys we wanted to simplify Our dashboard demo shows that it's both possible and easy to add rich data integrations from a static html page.