Backend API development guidelines

This is intended to be a collection of guidelines and best practices. The exact error response structure is under development.

API design

Types of responses

Currently we support these types of responses:

• Success (200 OK or 204 NoContent (for DELETE requests only)): entity or entity with warnings
• Partial success (200 OK, consider 207 MultiStatus): entity with errors
• Error (400 BadRequest or 404 NotFound): errors list
  • 404 NotFound must be returned for
    • absent routes
    • absent entities requested with GET having entity identifier in URL (e.g. GET /v1/foos/:fooId)
  • 400 BadRequest must be returned in any other case

Single responsibility principle for endpoints

Avoid (split into multiple) overly generic endpoints that

• have different behavior depending on optional attributes in payload
• require complex validation logic

External API (client)

Communication between core and UI. Client must be able to:

• render data based on successful response
• display error message or to build its own from error response

For thoughts on new error API, refer to this document

Internal API (between core and microservices)

Communication between phoenix and other microservices that are not supposed to be called by UI. Phoenix must be able to:

• build an error response to client if microservice call was initiated by client request
• handle failure in other case (TODO: fill this in)