Back to basics…

• REST API = a type of Application Programming Interface (API) that enables systems to communicate with each other through HTTP protocol
• Essential contract concept to make the communication clear and efficient through the definition of rules around endpoints, data format and setup, communication protocol, authorization, and error management (response codes).
• 4 main actions to access and manipulate data: GET to read, POST to create, PUT to update, DELETE to suppress.
• API design as a major prerequisite to make an API a success.
  • Think about the API before coding it
  • Ensure effective use before targeting possible reuse
  • Keep it simple, client-oriented and functional to make it available for anyone (no more technical terminology)
  • Make an API client-oriented is a priority #1, make it secure and unbreakable (HTTPS & OAuth2) is a priority #1 as well.
• Naming rules: see Naming convention & base path.
• More detailed information: internal reference documents (API Introduction, Detailed technical guidelines, first principles & guidelines summary) - contact the platform team for the latest versions.

Implementation approach

• Any new API to be developed in the future must stick to the guidelines (MUST at least), whatever the type of API:
  • Intra-application back to front
  • Inter-applications internal and external
• No request to rework all legacy APIs following the new guidelines, except in case of any change/evolution in the future that would require rewriting - e.g. opening an intra-application API to another application, switching from SOAP to REST for security purposes, etc.

Resources

The full set of guidelines is available from the platform team.

In this section