REST API Guidelines

Reliability

  • 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.
  • 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.
  • The Flowmailer REST API can be reached by multiple IP addresses. Retries should be done to different IP addresses to maximize availability.

Security

  • Always use HTTPs connections and check the validity of the offered certificate.
  • 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

  • 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.
  • Our service IP addresses change rarely, however, please connect using our DNS names and configure your environment to adhere to DNS record changes.

Performance

  • Authentication tokens are valid for multiple requests. Please use them for as long as they're valid, especially in batch processes.
  • Utilize HTTP keepalive, sending multiple requests using a single connection. Establishing HTTPs connections is relatively slow and should be avoided.
  • Enable HTTP Pipelining if possible.
  • 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

  • Avoid unnecessary load, for instance by requesting the same reports repeatedly with large overlapping dateranges.
  • 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.