Conventions

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.

HTTP Requests

All calls are secure HTTP requests to our RESTful API URLs. These can use the HTTP methods GET, POST, PUT and 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:

DELETE /v2/your-account-code/subscriber/someone@example.com/tags/SomeTag

Use:

POST /v2/your-account-code/subscriber/someone@example.com/tags/SomeTag?_method=DELETE

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.

Encryption

All requests must be over HTTPS. This is to protect the authorisation headers.

Compression

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.

Mandatory conventions

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:
  • application/xml
  • application/*
  • */*
  • *.*

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 application/xml or application/*.

• Must include the appropriate authentication headers.
• Must be prepared to respond to usage limitation responses.

Optional conventions

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 ETag¹. Used to determine whether a cached entity is out of date.
• May include If-Match header with the appropriate ETag¹. Use with PUT for optimistic concurrency control.

¹. If the entity and call in question supports ETags. See the documentation for specific entities and calls. ↩