API Guide: Reference View

The Reference view in the API Guide provides in-depth information into each API call available for Swiftly data. Each call will have documentation on what information it returns, the definitions of the parameters of that call, the common responses you may encounter, and a testing widget to test each call.

While you may only have access to certain specific API calls, you can view the documentation on all possible API calls in the Reference section. 

Overview of Reference Guide Sections

When you click on an API call on the left-hand side, you will see four main sections providing you more detail into each specific API call.

Introduction and Overview Section

This first section is in paragraph format. It will provide you the high-level details on what data the API call will provide, the parameters required for the call, and various filters you can add to specify what data you are receiving via the API.

Request Parameters

This section will go into granular detail about each parameter in the API call. This section will provide you information about the following:

• Name of the parameter
• Data type and format for each parameter
• Definition of what each parameter means 
• Whether a parameter is required

Keep in mind that all Path parameters will be required since they tell the Swiftly system which API you're interested in, but query parameters tend to be optional. Think of the query parameters as filters to the data - they allow you to specify exactly what API information you want.

Responses

This section goes over all potential responses you can get from an API call. The tabs correspond with each response code. Under each tab, you will find an example of each response and the schema that shows the code details for each response.

Testing widget 

The final section of the reference documentation is a testing widget. This widget allows you to test an API call within the Swiftly platform and provides a way to see what kind of information you need to input plus the data output from API call. Details on how to run a test call below. 

How to run a test call

Step 1: Select an API call from the left-hand side list

Step 2: Go to the bottom of the page where it says "Send a Test Request"

Step 3: Start in "Settings" and fill out the "Path Params." This will typically require you to input the agencyKey and any other call-specific requirements. 

In my example, I will need to input an agency key and a routeKey. 

Step 4: Double-check the "Authorization" which is the API key.

Step 5: Double-check the API link and that it is for the correct information.

Step 6: Go to the "Query" tab. 

Step 7: Fill out the parameters you would like to include in the test call--make sure to include any required parameters indicated in the "Request Parameter" section above. Follow the format for each parameter based on the "Request Parameter" documentation above. 

In my example, I filled out the start and end date parameters plus being and end time. These parameters set a date and time range for the data I'm receiving.

Step 8: Go to the "Code Generation" tab and select your language and library for the API call. 

In my example, I will leave it as the default "Shell" and "cURL."

Step 9: Click the "Send" button to run your test call. 

If set up correctly, the API test call should have a "running" text under the test widget. It can take anywhere from a few seconds to a few minutes to run a call, but once successful you will get all the data from the call in the test widget. This is what your API call will return and can give you an idea of what information you will receive once the API call is set up in your systems. 

Next Steps With Your API Test Call 

Once you test an API call and receive results, you can use the test call output directly in your actual API Call. By clicking on the "Original Request" tab, you will have access to the original call request with all the path and query parameters included. You can copy the http request and paste it directly into your own API call or script - this call will have all the information needed to access information on the Swiftly side of the API.