This lesson has notes and guides only.
If you wish to use our SDK Files, visit our GitHub here. Note, that the Authenticate endpoint needs to be completed once, then it should automatically reauthenticate.
Before using our SDK files, please be aware of some limitations:
Should you need any help or further information with SDK Files, please reach out to sujith@compassiot.com.au.
00:00
In this video we're going to go over what an API is and why you might use one. So what exactly is an API? An API stands for Application Programming Interface. Basically, it's a tool that lets you connect to a software application and request specific data, like placing an order.
00:16
Think of it like this. You're at a restaurant. You tell the waiter what you want and they bring it to you. In this scenario, the API is the waiter passing your requests to the kitchen and bringing you your order. But how do you make a clear request? Saying “I want food” is too vague. You need to be more specific. How do you tell it you want a burger or a salad?
00:32
In the API world, these specific requests are called endpoints. Endpoints are like items on a menu. They let you ask for exactly what you want. So the system, or in our scenario kitchen, knows how to respond.So to recap, an API is the messenger between you and the system, and endpoints are the things you ask for.
00:53
Now let's talk about the two main types of APIs you might come across.
00:56
The first type is unary APIs. These are simple one time exchanges. You make a request and you get one response back. It's like ordering a burger and the waiter brings you a burger.
The other type is streaming APIs. These APIs are like an ongoing conversation. You make a request and the API will keep sending you updates and chunks of data as they are ready. It's like asking the waiter to keep bringing you different meals throughout the night dish after dish.
01:19
So why would you use an API? Specifically for Road Intelligence, APIs help perform large scale queries like long date ranges, big areas, or complex multi selections that would be difficult to do on the platform. APIs can also help automate queries at regular intervals, saving you time and help ingest data into your own data pipeline, models and dashboards.
01:42
Now that you know what an API is, the different types and why you might use it. Let's walk you through your first step. Using the Authenticate endpoint.
01:50
The Authenticate endpoint provides an access token, authenticating and allowing you to use the other endpoints like a key. We'll show you how to complete the endpoint on the Road Intelligence Docs.
02:01
First select Authenticate endpoint on the left hand side.On the Docs tab, you'll see what information the API needs from you and what you will receive in its response. So we will need to provide your API client token. This is a string of characters provided at a workspace level, meaning there is only one API client token per organisation.
02:22
Someone in your team should have it, but if you get stuck, the Compass team can help. Next we'll go to the Try It tab. Paste your token or API key into the text field here and click Submit. You'll see a success banner appear in the top right of the screen.
02:37
Now you're authenticated. If you go to use another endpoint, you'll see that You are Authenticated confirmation in the top right. Just note you'll need to repeat this process and re-authenticate every 70 minutes when using our API docs. And that's it. In this lesson we learned what an API is, the types of available, why you might use it, and how to get started by completing the Authenticate endpoint.
We'd love to hear what you think. Leave your details below if you'd like to be contacted.