All calls to the Poppulo API must obey these calling conventions. Failure to do so is a common source of errors. Most browsers obey these conventions, as do many REST libraries.
All calls are secure HTTP requests to our RESTful API URLs. These can use the HTTP methods
DELETE. In some cases, you may not be able to issue PUT or DELETE requests directly (e.g. they are forbidden by firewall rules). In this case, you can still make the requests by issuing HTTP
POST requests with the HTTP parameter _method set to the “actual” method.
For example, instead of:
It is important to test whether such HTTP methods are allowed on your production system early, because it is inconvenient to retrofit all such requests, and firewall rules may differ between production and development environments.
All requests must be over HTTPS. This is to protect the authorisation headers.
HTTP Compression is optional – but is recommended. It will improve the performance of your Poppulo API application and reduce the bandwidth it uses. Using HTTP Compression may affect the frequency and duration of usage limitation responses. It may also affect the number of items returned in paged responses.
The following rules are mandatory. All calls:
- Must be HTTP/1.1 compliant (i.e. must have the correct Host header).
- Must include a non-empty User-Agent header. We recommend that you include your company name in this string.
- Must include an Accept header with any of the values:
Please note that the Accept header must be in this list, even if the call would appear to return HTML, CSV, images or some other type. This is because any call could result in an error, and errors are represented by a Status XML Entity. If such a call is successful, we will return the HTML, CSV or image data (with the correct
Content-Type, even if you specify
- Must include the appropriate authentication headers.
- Must be prepared to respond to usage limitation responses.
The following suggestions are optional. Calls:
- May include a Accept-Encoding header of compress or gzip. Strongly recommended
- May include If-None-Match header with the appropriate ETag1. Used to determine whether a cached entity is out of date.
- May include If-Match header with the appropriate ETag1. Use with PUT for optimistic concurrency control.