Integration Considerations

When planning an integration with the Navigatr API, it is essential to consider and answer specific key questions. These inquiries provide crucial guidance, enabling a streamlined and effective integration process. They include understanding the user journey, data implications, existing solutions, intended technology stack, and any budget or timeline constraints.

• Clarifying the intended user journey

Understanding the specific path and experience that the end-users are expected to undergo, ensuring that the integration aligns with and enhances this journey, leading to a more user-friendly and intuitive experience.

• Understanding data implications

Grasping the impact that the integration process may have on data flow, management, and security, ensuring the seamless transfer and safeguarding of data between systems.

• Assessing the availability of existing solutions

Identifying any pre-existing frameworks, applications, or systems that can be utilized or built upon to streamline the integration process and leverage prior investments.

• Identifying your existing and intended technology stack

Recognizing the specific technologies and tools at your disposal, enabling the integration to seamlessly integrate with the existing infrastructure and technology ecosystem.

• Evaluating your access to a development team and their capacity

Understanding your internal resources and capabilities, ensuring that the integration process can be adequately supported and executed with the available resources.

• Determining the desired timeline

Establishing a clear understanding of the expected timeframe for the integration process, allowing for the creation of realistic milestones and objectives that align with your requirements and expectations.

• Establishing the allocated budget

Defining the financial resources allocated for the integration process, ensuring effective cost management and resource allocation throughout the integration project.

Authentication

We use a dedicated authentication server for handling login requests. As a result, logging in to the API requires a username and password.

Bearer tokens are short-lived and need to be renewed periodically. Tokens expire after 5-15 minutes.

Logging in

Call the endpoint /v1/token to get the bearer token.

POST https://api.navigatr.app/v1/token
Data: {
    "username": "someone@example.com",
    "password": "password"
}

Returns:

{
    "access_token": "xxxyyyzzz"
}

When making calls to other endpoints, include this token in the request header:

GET https://api.navigatr.app/v1/user_detail/0
Headers:
    - Authorization: Bearer xxxyyyzzz

Python Example

# Get the token
r = requests.get("https://api.navigatr.app/v1/token", data={"username": "someone@example.com", "password": "password"})
token = r.json().get("access_token")

# Try an authenticated endpoint
r = requests.get("https://api.navigatr.app/v1/user_detail/0", headers={"Authorization": f"Bearer {token}"})
print("Hello", r.json().get("firstname"))

Responses

HTTP Response Codes

These are the kinds of HTTP responses you can expect from the API.

Successful responses return 200 Success. In some cases, they may be 202 Accepted depending on context.

If you're lucky enough to ever encounter a 50x error, please let us know by raising a support ticket.

Media URLs

If your application or network is required to audit and approve URLs, the API may link to resources hosted at these domains:

• media.navigatr.app
• images.credly.com

Pagination

If the API response includes a list, the pagination information will be included at the bottom of the response.

{
    "items": [
    ...
    ],
    "total": 37,
    "page": 1,
    "size": 50
}

Total: the total number of items across all pages.

Page: the current page number as per request. The default is 1. This can be changed to read the data from other pages.

Size: the page size as per defined in the request. This refers to the number of items per page. The default is 50. This can be changed based on requirements in order to receive fewer or more items per page.

Rate Limiting

Our API operates under a rate limit policy to ensure optimal performance and reliability for all users. To maintain the stability of our services, we have set a limit of 5 requests per 2-second interval. It is essential for all users to adhere to this restriction. Exceeding the allowable request limit will result in a 429: Too Many Requests response. In such cases, users are encouraged to retry their requests after a 2-second interval. This measure has been implemented to prevent service disruptions and to ensure equitable access for all API consumers.

We advise developers and users to incorporate appropriate mechanisms within their applications to comply with the specified rate limit. This may involve implementing request queuing, backoff strategies, or other similar approaches to ensure adherence to the rate limit policy.