Differences

This shows you the differences between two versions of the page.

--- en:outskirts:mages-peaks:api [2024/07/14 14:55] – [GET /character/{character_id}] YannZeRookie
+++ en:outskirts:mages-peaks:api [2024/10/28 08:00] (current) – external edit 127.0.0.1
@@ Line 4: / Line 4: @@
 Also check out the [[en:outskirts:mages-peaks:sso|The Laelith Authentication]].
+==== General Philosophy of the API ====
+When dealing with any API, there are usually two types of philosophies: strict ones and permissive ones.
+In a **strict API**, the server (and the client) throws an error when it does not get exactly the schema it was expecting. So extra or missing fields would trigger an error. The reasoning is that it is a smell and we don’t want to risk corrupting any data. This introduces strong coupling, and therefore the need to define so-called "api versions" and have both the client and the server check each-other to make sure that they are compatible.
+In a **permissive API**, the server (and again, the client), won’t throw an error most of the time. If a field was missing, a default value is used. And any extra field will simply be ignored. This introduces loose coupling.
+Both approaches have advantages and disadvantages. The strict approach is usually preferred in corporate contexts with strong IT and/or business stakes. The permissive approach is more suited to flexible and fast development, but requires to write a bit more of backward-compatibility code.
+Another example: in a strict API, a non-relevant field will still be provided but with a ''null'' value. In a permissive API, it will be omitted.
+**For the sake of simplicity and flexibility, the permissive approach was chosen for the Laelith API**. Irrelevant fields are omitted. Unknown fields are ignored. Meaningful default values should be used as much as possible, and end-points should fail only when something really required is missing or malformed.
 ==== GET /hello ====