Skip to content

Commit

Permalink
docs: fix page headers order
Browse files Browse the repository at this point in the history
  • Loading branch information
@EdieLemoine
EdieLemoine committed Oct 11, 2023
1 parent c55e5a9 commit 2a27a3e
Show file tree
Hide file tree
Showing 7 changed files with 195 additions and 296 deletions.
88 changes: 33 additions & 55 deletions src/api-reference/01.requests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,77 +40,55 @@ User-Agent: CustomApiCall/2 Node/18.13.0

## 1.C HTTP methods

The API is REST(ful) and uses JSON as its primary data exchange format.
Communication with the API goes through HTTPS thereby insuring data
confidentiality and integrity. Here is a list of all supported HTTP methods
The API is REST(ful) and uses JSON as its primary data exchange format. Communication with the API goes through HTTPS thereby insuring data confidentiality and integrity. Here is a list of all supported HTTP methods

### 1.C.1 GET

GET method is used for retrieving data and is idempotent. Data can be returned
in JSON, PDF, CSV, XML or other formats.
GET method is used for retrieving data and is idempotent. Data can be returned in JSON, PDF, CSV, XML or other formats.

### 1.C.2 POST

POST is used to create new objects or send data to MyParcel.

### 1.C.3 DELETE

DELETE is used to delete an existing object (piece of data). This method always
returns <Http code=204 /> unless otherwise specified.
DELETE is used to delete an existing object (piece of data). This method always returns <Http code=204 /> unless otherwise specified.

### 1.C.4 PUT

A PUT request creates a resource or updates an existing resource. The client for
specifies the URI for the resource. The request body contains a complete
representation of the resource. If a resource with this URI already exists, it
is replaced. Otherwise, a new resource is created, if the server supports doing
so.
A PUT request creates a resource or updates an existing resource. The client for specifies the URI for the resource. The request body contains a complete representation of the resource. If a resource with this URI already exists, it is replaced. Otherwise, a new resource is created, if the server supports doing so.

### 1.C.5 PATCH

A PATCH request performs a partial update to an existing resource.
The client specifies the URI for the resource. The request body specifies a set
of changes to apply to the resource. This can be more efficient than using
A PATCH request performs a partial update to an existing resource. The client specifies the URI for the resource. The request body specifies a set of changes to apply to the resource. This can be more efficient than using

## 1.D Rate limiting

Default rate limits apply to many of our documented endpoints.
Customers who would like a higher rate limit can contact us to discuss the possibilities
(e.g. increasing the limit, or using a webhook).
When the limit is reached for a Method/Endpoint combination, any additional call will return
an HTTP 429 (Too Many Requests), effectively ignoring the request.
A sliding window is used to determine the rate limit.
Calls resulting in an HTTP 429 also count as requests, so it is better to wait a while before retrying than continually
retrying and getting additional HTTP 429 responses.
Waiting 5 minutes will definitely reset the rate limit for the used Method/Endpoint combination.

Example: If you make 100 GET requests within 15 seconds to the same endpoint with an
allowed rate limit of 100 request per 5 minutes, you will only be able to continue sending GETs 4 minutes 45
seconds later. Sending some POSTs to the same endpoint is allowed though, it follows its own rate limit.

| Method | Endpoint | Rate limit |
| ------ | ----------------------------------------------- | -------------------------- |
| GET | `/` | 30 calls in 5 minutes \* |
| GET | `/delivery_options` | 300 calls in 5 minutes |
| GET | `/drop_off_points` | 300 calls in 5 minutes \* |
| GET | `/fulfilment/orders` | 300 calls in 5 minutes \* |
| POST | `/fulfilment/orders` | 100 calls in 5 minutes \* |
| PUT | `/fulfilment/orders` | 100 calls in 5 minutes \* |
| GET | `/fulfilment/orders/{identifier}` | 300 calls in 5 minutes \* |
| DELETE | `/fulfilment/orders/{identifier}` | 300 calls in 5 minutes \* |
| GET | `/fulfilment/orders/{identifiers}/packing_slip` | 100 calls in 5 minutes \* |
| GET | `/pickup_locations` | 300 calls in 5 minutes |
| POST | `/return_shipments` | 300 calls in 5 minutes \* |
| GET | `/shipments` | 500 calls in 5 minutes \* |
| PATCH | `/shipments` | 300 calls in 5 minutes \* |
| POST | `/shipments` | 500 calls in 5 minutes \* |
| PUT | `/shipments` | 300 calls in 5 minutes \* |
| GET | `/shipments/{ids}` | 1000 calls in 5 minutes \* |
| DELETE | `/shipments/{ids}` | 300 calls in 5 minutes \* |
| GET | `/shipment_labels/{ids}` | 500 calls in 5 minutes \* |
| GET | `/tracktraces/{ids?}` | 300 calls in 5 minutes |
| GET | `/webhook_subscriptions` | 150 calls in 5 minutes |
| POST | `/webhook_subscriptions` | 30 calls in 5 minutes |
| DELETE | `/webhook_subscriptions` | 30 calls in 5 minutes |

Note: Rate limits for endpoints marked with \* will be applied on August 1st, 2023.
Default rate limits apply to many of our documented endpoints. Customers who would like a higher rate limit can contact us to discuss the possibilities (e.g. increasing the limit, or using a webhook). When the limit is reached for a Method/Endpoint combination, any additional call will return an <Http code=429 /> (Too Many Requests), effectively ignoring the request. A sliding window is used to determine the rate limit. Calls resulting in an <Http code=429 /> also count as requests, so it is better to wait a while before retrying than continually retrying and getting additional <Http code=429 /> responses. Waiting 5 minutes will definitely reset the rate limit for the used Method/Endpoint combination.

Example: If you make 100 GET requests within 15 seconds to the same endpoint with an allowed rate limit of 100 request per 5 minutes, you will only be able to continue sending GETs 4 minutes 45 seconds later. Sending some POSTs to the same endpoint is allowed though, it follows its own rate limit.

| Method | Endpoint | Rate limit |
| ------ | ----------------------------------------------- | ----------------------- |
| GET | `/` | 30 calls in 5 minutes |
| GET | `/delivery_options` | 300 calls in 5 minutes |
| GET | `/drop_off_points` | 300 calls in 5 minutes |
| GET | `/fulfilment/orders` | 300 calls in 5 minutes |
| POST | `/fulfilment/orders` | 100 calls in 5 minutes |
| PUT | `/fulfilment/orders` | 100 calls in 5 minutes |
| GET | `/fulfilment/orders/{identifier}` | 300 calls in 5 minutes |
| DELETE | `/fulfilment/orders/{identifier}` | 300 calls in 5 minutes |
| GET | `/fulfilment/orders/{identifiers}/packing_slip` | 100 calls in 5 minutes |
| GET | `/pickup_locations` | 300 calls in 5 minutes |
| POST | `/return_shipments` | 300 calls in 5 minutes |
| GET | `/shipments` | 500 calls in 5 minutes |
| PATCH | `/shipments` | 300 calls in 5 minutes |
| POST | `/shipments` | 500 calls in 5 minutes |
| PUT | `/shipments` | 300 calls in 5 minutes |
| GET | `/shipments/{ids}` | 1000 calls in 5 minutes |
| DELETE | `/shipments/{ids}` | 300 calls in 5 minutes |
| GET | `/shipment_labels/{ids}` | 500 calls in 5 minutes |
| GET | `/tracktraces/{ids?}` | 300 calls in 5 minutes |
| GET | `/webhook_subscriptions` | 150 calls in 5 minutes |
| POST | `/webhook_subscriptions` | 30 calls in 5 minutes |
| DELETE | `/webhook_subscriptions` | 30 calls in 5 minutes |
Loading

0 comments on commit 2a27a3e

Please sign in to comment.