Differences

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

--- en:outskirts:mages-peaks:api [2024/07/07 13:45] – [GET /cadastre/{id}/obj] 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 ====
@@ Line 54: / Line 69: @@
 ==== GET /cadastre/{id}/obj ====
-Get a Wavefront OBJ file for Cadastre element.
+Get a Wavefront OBJ file for the Cadastre element.
 The 3D coordinate system is different than the 2D system of the map. Vertex (0,0,0) is at the bottom left (=southwest) corner. This ensure best compatibility with 3D softwares such as Blender: direct coordinate system, with X pointing east, Y pointing north, and Z pointing up.
@@ Line 132: / Line 147: @@
 Example: https://api.laelith.com/user/1
-==== GET /character/{character_id}====
+==== GET /character/{character_id} ====
 Get details about a character. Result includes the id of the user the character belongs to.
@@ Line 138: / Line 153: @@
 Example: https://api.laelith.com/character/1
+==== GET /character/{character_id}/avatar ====
+Get the avatar image of a character. This will not return a JSON but make a redirect to the image url.
+Note: it returns the //current// image of the character. If you want to see the image that was originally generated by the IA, add ''?original=1'' to the url. Example: https://api.laelith.com/character/44/avatar?original=1
 ==== GET /character/{character_id}/lots ====