REST API Guidelines

In this article you will read the best practices of a REST API:

• Reliability
• Security
• Maintainability
• Performance
• Fair use

Reliability

1. Messages that are submitted to Flowmailer will be confirmed by a 201 Created response. Only when this response is received, a source system should assume the message will be handled by Flowmailer.
2. In any system integration, eventually individual calls will fail. To prevent loss of messages, a retry mechanism, preferably backed by a queue system, is required.
3. The Flowmailer REST API can be reached by multiple IP addresses. Retries should be done to different IP addresses to maximize availability.

Security

1. Always use HTTPS connections and check the validity of the offered certificate.
2. Use separate credentials for different source systems and instances. Also, make sure these credentials have their minimum required role assigned; i.e. you don't need Admin privileges to submit messages.

Maintainability

1. Your client should accept any valid certificate if a trustworthy chain can be established. Please do not register the current certificate in use, to prevent problems when it's replaced.
2. Our service IP addresses change rarely, however, please connect using our DNS names and configure your environment to adhere to DNS record changes.

Performance

1. Authentication tokens are valid for multiple requests. Please use them for as long as they're valid, especially in batch processes.
2. Utilize HTTP keepalive, sending multiple requests using a single connection. Establishing HTTPS connections is relatively slow and should be avoided.
3. Enable HTTP Pipelining if possible.
4. If you need more performance and eliminate the effects of latency, please feel free to connect up to 10 times concurrently, especially when submitting messages.

Fair use

1. Avoid unnecessary load, for instance by requesting the same reports repeatedly with large overlapping date ranges.
2. Engineer the whole of your processes in an efficient way. For instance, if you want to receive all events for all messages, you should use the message_events call instead of, for instance, repeatedly requesting the status for each message.
   ‍