Best Practices

Introduction

This section summarizes the main rules to follow when implementing the call to Sage Active Public API V2 in your standard or specific applications.

Authentication

Sage Active Public API V2 is secured by Oauth 2.0.

Refer to the relevant sections for more details. How to find?

Relationship between tenant, organizations and users

To access the data of a resource, it is necessary to retrieve:

  1. The endpoint userProfile is used to retrieve the X-tenantId of the user.
  2. The endpoint organizations is used to get the list of organizations of the current subscription.
    That to retrieve a X-OrganizationId.

Refer to the relevant sections for more details:

Pagination

The notion of pagination is fundamental.
Your developments should be in line with the maximum number of records that the Sage Active Public API V2 returns on each call.

Find here the direct link relating to the pagination:
Key concepts / API - Pagination

Updating records

The focus is on modifying only the specific fields that need to be changed within the record, rather than sending the entire dataset.
This approach ensures efficiency and minimizes unnecessary data transfer.

Find here the direct link relating to the update of records:
Key concepts / Updating records

GraphQL Complexity limit

Managing complexity is crucial when working with the Sage Active Public API V2 to ensure optimal performance and efficient query execution.
The complexity of a GraphQL query is determined by various factors, including the number of fields requested, the depth of nested selections, and any custom business logic implemented in resolvers.

To maintain a well-performing GraphQL API, it is important to carefully consider and manage the complexity of your queries.
By optimizing your queries and minimizing unnecessary data retrieval, you can improve overall response times and reduce the computational load on the server.

Find here the direct link relating to the complexity:
Key concepts / GraphQL Complexity Limit

Sage Active Public API V2 usage limits

To ensure the availability and integrity of Sage Active Public API V2 at all times, a call count limit has been set.
The rate limit is set for each unique client application with the following limitations:

Rate limit of 3000 requests per application per minute.

If one of the limits is exceeded, Sage Active Public API V2 will return an HTTP error code 429 (Too many requests). We recommend that you take this possible error code into account when developing your application in order to prevent one of the aforementioned limits from being reached.

Caching

Exceeding API limits can be problematic for any application or user experience.
To ensure that your application is as efficient as possible, considering the types of data you obtain and manage should help you highlight data types that are static or rarely updated.
Static data is constant and can be shared for all users of the same language without the need to reread it systematically.

Example: The list of journal Types can be loaded when the application is launched, without having to be read again on each call.

Multi-thread access

To help and maintain data integrity, extra care should be taken when parallel mutations are executed.
We recommend that you do not use parallel mutations when creating data that may have unique references or use system-generated sequential numbering.
In particular, avoid making parallel mutations when adding AccountingEntry.

Storing Authentication Tokens

Storing authorization and refresh tokens generated from the OAuth 2.0 flow is a widely discussed topic on the web.
Solutions and guidance vary depending on the type of application you have created, the OAuth 2.0 documentation is a good reference to the patterns your flow should follow and are based on the type of application.
If possible, try to reduce the number of times a user has to reauthenticate in your application.
For example, a native web application with its own backend storage should be able to securely store tokens and authorize user access without having to re-authenticate after each session.

Type mismatch

Type mismatch can be frustrating for the user and can also be a factor in exceeding API consumption limits.
The most common misuse of types is for broken business rules.

Example: You are trying to import accounting entries and one of these rules is not respected:

  • Respect of maximum lengths for string properties,
  • Journal code must exist in resource journalType, property code,
  • Date of document must be in the interval dateDebut and dateEnd of an unclosed financial year,
  • General account code must exist in the resource AccountingAccount, property code,
  • Third-party code, if specified, must exist in the resource Customers, Suppliers,Employes property code,
  • All of the entries in a document must be balanced (Total Debit amount = Total Credit amount)

Translation

Field lengths and enumerations.

It is up to the developer to respect the lengths of properties of type string as well as the values of enumerations.
The Sage Active Public API V2 reference manual specifically describes maximum lengths, enumeration values, required values, etc.
API resources overview