1. Requests

# 1.A Base URL

BaseURL: https://api.myparcel.nl

# 1.B User-Agent

To give us insight into where requests come from and API documentation usage, you should send a User-Agent header with all your requests. This header should include information about your integration, the CMS/platform and the backend you are using.

We recommend the following format and order:

MyParcel-<integration>/<version> <cms>/<version> <backend>/<version>

Example, given you're using a CMS called "My First CMS", its version is 3.0.0 and it runs on PHP 8.1.0:

User-Agent: MyFirstCMS/3.0.0 PHP/8.1.0

An example if you're building a MyParcel plug-in for "My First CMS" and its version is 1.0.0:

User-Agent: MyParcel-MyFirstCMS/1.0.0 MyFirstCMS/3.0.0 PHP/8.1.0

Example if you are building a custom API implementation and are running Node 18.13.0:

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

# 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.

# 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 204 No Content 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.

# 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

# 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 (Too Many Requests), effectively ignoring the request. A sliding window is used to determine the rate limit. Calls resulting in an HTTP 429 Too Many Requests also count as requests, so it is better to wait a while before retrying than continually retrying and getting additional HTTP 429 Too Many Requests 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.