API Style is REST Level 3

Acronym

sig-api-style

Belongs to

SIG APIs

Responsible

jalue und SohleDelfin6504

History

(v1)   2021-01-11 - created initially

(v2)   2021-01-12 - update responsibility

(v3)   2021-01-12 - need for decision

(v4)   2021-01-12 - sources and evaluation

(v5)   2021-01-22 - updated deadline

(v6)   2021-01-28 - add Resolution

(v7)   2021-02-12 - state back to 4, how-to needed

Why is there need for such a decision?

The Api-Style defines the way users can access the provided resources. The Goal should be that all APIs can be accessed the same way, so the Client/User does not need different ways to access. Moreover, by using the same api style it will be easier to extend the functionality of the api. In addition to that it will be easier to understand.

All Teams must use the same style to reach this goal.

Additional sources for better understanding the background

• Differences between SOAP and REST
• GraphQL
• REST Levels
• Building a GraphQL API - video
• REST, SOAP or GraphQl

Viable Options

• REST level 2
• REST level 3
• GraphQL

Alternatives not seriously considered

• Soap : not considered because it produces a lot of Overhead due to XML syntax
• gRPC : not considered because it is made for realtime use cases, which is not required here

How is this decision evaluated?

To take the decision, research is necessary. Therefore, the differences between the different API-Styles have to be evaluated. It is important that after the research, the preferred styles are implemented as prototype to compare them directly and get familiar with those styles. In specific the domain of the requirements is going to be implemented. As a first prototype basic methods are going to be implemented:

• get all : returns all Objects
• get for id : returns one Object by id
• create : creates a new object
• update : updates an existing object

With the results of the research a decision based on facts and experience can be taken.

Different aspects are going to be relevant for the decision:

• Usability
• an existing documentation of the protocol
• standards
• does it fulfill all relevant aspects needed for the communication between backend and frontend
• Safety of the protocol

Resolution Details

The Decision is that Rest must be used as api style. In specific Rest level 3 must be used. An example of how to implement can be found in the PoC Rest Level 3.

Reasons for the resolution

The Explanation of the resolution can be found in the wiki.