Skip to main content

Recent posts

Rate Limiter Updates

Anton Kabysh

Software Engineer

Rate Limiter for Multi-Root Queries#

This blog post describes upcoming changes in rate-limiter for Maritime 2.0.

Recently we introduced rate-limiter to prevent DDoS attacks and gracefully handle load to Maritime 2.0 API. The full documentation on rate limit behavior is now available and could be found here.

As we see gradual adoption of multi-root queries among our customers we have to revise our rate-limiter policy to handle such cases appropriately. Because each root query executed in parallel and represents a complete and self-sufficient request to our underlying API we should treat each root query as independent request and count it as one from the rate limiter perspective. So with new rate limiter policy, multi-root queries will be treated as several independent requests for rate limiter.

For example, currently the following query is treated as 1 request. After the update it will be counted as 2 standalone queries:

{
# first query for tankers
tankers: vessels(shipType: [TANKER_CRUDE, TANKER_PRODUCT, TANKER_CHEMICALS]) {
nodes {
staticData {
mmsi
name
}
}
}
# second query for cargo
cargo: vessels(shipType: [CONTAINER, GENERAL_CARGO]) {
nodes {
staticData {
mmsi
name
}
}
}
}

The response with a new policy will look like:

{
"data": {
"tankers": { ... },
"cargo": { ... }
},
"extensions": {
"requestQuota": {
"limit": "60 req/m (burst 60)",
"remaining": 58
}
}
}

As you can see, rate limiter subtracted 2 from the remaining quota, one for cargo and one for tankers.

Breaking Changes#

There is also a subtle breaking change in the API which might be important for data integrators. To cope with wider usage of multi-root queries we should adjust data format for some edge cases.

For example, taking a multi-root query bellow, imagine the tankers query completed successfully, but the cargo query timed out for some reason. In this case we still can return a partial response with tankers data alongside with an error for cargo.

{
tankers: vessels(shipType: [TANKER_CRUDE, TANKER_PRODUCT, TANKER_CHEMICALS]) {
...
}
cargo: vessels(shipType: [CONTAINER, GENERAL_CARGO]) {
...
}
}

Before the update it was not possible and the response would look in the following way. As you can see the entire response is empty by {"data": null}.

{
"data": null,
"errors": [{
"message": "This request timed out",
"path": ["cargo"],
"extensions": {
"code": "TIMEOUT_ERROR"
}
}],
"extensions": {
"requestQuota": {
"limit": "60 req/m (burst 60)",
"remaining": 58
}
}
}

We fixed that edge case and the response would look like:

{
"data": {
"tankers": { ... },
"cargo": null,
},
"errors": [{
"message": "This request timed out",
"path": ["cargo"],
"extensions": {
"code": "TIMEOUT_ERROR"
}
}],
"extensions": {
"requestQuota": {
"limit": "60 req/m (burst 60)",
"remaining": 58
}
}
}

Those change also affecting simple queries as well. For example, if error will happens in case of the following query:

{
vessels(shipType: [TANKER_CRUDE, TANKER_PRODUCT, TANKER_CHEMICALS]) {
nodes {
staticData {
mmsi
name
}
}
}
}

The response might contain data: null or data: { vessels: null } depending on the nature of the error.

{
"data": null,
"errors": [...],
}
// or
{
"data": {
"vessels": null
},
"errors": [...],
}

The second case was not possible earlier and we encourage our customers to handle this case in your Spire API client.

End.

Maritime 2.0 Release Documentation

Bruce Bookman

Bruce Bookman

Maritime Software Quality Assurance

Maritime 2.0 assets have been updated for the General Availability Release and the Beta assets have been deprecated. The refreshed documentation includes:

Some updates from Maritime 2.0 Beta include:

If you have any suggestions on how we can improve our documentation, please let us know your thoughts in our Contact Us form.

New & Improved Documentation

MacKenna Kelleher

MacKenna Kelleher

Maritime Technical Sales Engineer @ SpireGlobal

Thank you for signing up for the Vessels V2 Beta.

We are very excited to offer you a new and improved documentation website, with more tutorials and quality content to come.

If you have any suggestions on how we can improve our documentation, please let us know your thoughts in our Contact Us form.