---
title: "API design guide"
description: "Core principles for designing REST APIs at SCOR."
url: "https://portal.apim-ne-sail-dev.sf.scor.fr/readme-guidelines/api-design-guide"
image: "https://portal.apim-ne-sail-dev.sf.scor.fr/_og/d/c_Ocean.takumi,title_API+design+guide,description_Core+principles+for+designing+REST+APIs+at+SCOR.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDgwQTkifX19,p_Ii9yZWFkbWUtZ3VpZGVsaW5lcy9hcGktZGVzaWduLWd1aWRlIg,s_1uU9iKs067IRxgrE.png"
---

Guidelines

## API design guide

Core principles for designing REST APIs at SCOR.

[README & Guidelines](https://portal.apim-ne-sail-dev.sf.scor.fr/readme-guidelines) / API design guide

### [Back to basics…](#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](https://portal.apim-ne-sail-dev.sf.scor.fr/readme-guidelines/api-design-guide/naming-convention).
-   **More detailed information:** internal reference documents (API Introduction, Detailed technical guidelines, first principles & guidelines summary) - contact the [platform team](https://portal.apim-ne-sail-dev.sf.scor.fr/readme-guidelines/contacts) for the latest versions.

### [Implementation approach](#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](#resources)

The full set of guidelines is available from the [platform team](https://portal.apim-ne-sail-dev.sf.scor.fr/readme-guidelines/contacts).

### [In this section](#in-this-section)

[](https://portal.apim-ne-sail-dev.sf.scor.fr/readme-guidelines/api-design-guide/naming-convention)

### [](https://portal.apim-ne-sail-dev.sf.scor.fr/readme-guidelines/api-design-guide/naming-convention)[Naming convention & base path](#naming-convention-base-path)

The mandatory naming pattern for every API - source, business domain, functional object, and more.