Differences

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

--- en:outskirts:mages-peaks:api [2024/02/02 13:09] – [GET /cadastre/{id}/preview] 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 48: / Line 63: @@
 ==== GET /cadastre/{id}/mapview ====
+==== GET /cadastre/{alias}/mapview ====
-Return a 400x400 PNG file that shows a map image of a Cadastre element.
+Return a 256x256 PNG file that shows a map image of a Cadastre element.
+==== GET /cadastre/{id}/obj ====
+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.
+In Blender, when using the OBJ import feature, choose "Y" for the "Forward Axis" and "Z" for the "Up Axis".
 ==== GET /network ====
@@ Line 90: / Line 113: @@
 Altitude 0 is the lake. Values go from about -750 m to +1300 m.
+==== GET /heightmap/obj ====
+Get a Wavefront OBJ file of the Height Map.
+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.
+In Blender, when using the OBJ import feature, choose "Y" for the "Forward Axis" and "Z" for the "Up Axis"
 ==== GET /cache ====
@@ Line 115: / 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 121: / 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 ====
@@ Line 134: / Line 171: @@
 Get an English and French translation table of the Ontology.
+==== GET /ai/hello ====
+Test if the AI service is up-and-running.
+==== POST /ai/names ====
+Generate a list of character names.
+  * **species**: "human" (default), "dwarf", "elf", "gnome", "felys", "orc", "gopneldaun", "halfling", "half-elf", "half-orc", or "utruz". You can use other values at your own risks.
+  * **gender**: "male" (default) or "female".
+  * **origin**: "laelith" (default), "grand duchy of agramor", "azilian march", "egonzasthan shires federation", "gardens of jadhys", "barony of kaoca", "matriarchate of olizya", "outskirts", or "beyond the sunset marches". You can use other values at your own risks.
+  * **lang**: language: "en" (default) or "fr"
+  * **count**: integer, number of names to generate. 8 by default.
+==== POST /shell/claim ====
+Allows the Logged-in user (identified by its Bearer Token) to claim a Shell Code (Invitation).
+This creates a 'character_slot' asset and transfers the Elith associated with the Invitation to the user.
+This operation is Captcha-protected.
+==== GET /myassets ====
+Returns the list of Assets owned by the logged-in user.
+==== PUT /assets/character/{character_id} ====
+Allows to update the Name and/or Avatar of the Player Character of the specified ID (owned by the logged-in user).