9.5 KiB
API Documentation
Introduction
This documentation explains the API for the ENcarteS project for AliENS. The backend is based on Symfony 8.2, check the README.md to install it. To make a request to the API you should request("https://encartes.aliens-lyon.fr/api/map/FUNCTION/ARGUMENT1/ARGUMENT2...") (for local use, replace https://encartes.aliens-lyon.fr/ by http://127.0.0.1:8000/)
It has been authored by Basile Leretaille & Samy Avrillon Other participants for this project are Adrien Vannson & Gabriel Dehame & Maxime Just & Tristan Klein
Functions
/api/map/get_floor/ID/REPRESENTATION
Return a json with siteId, buildingId and 'places': a list of place composing floor ID REPRESENTATION is the representation' type to consider for every places in {'Cylinder', 'PolySurface'}. The default is 'Cylinder' Other representations should be added later, and it should become a priority order instead of a strict selection (actually if a place doesn't have Cylinder representation, it will return an empty list, even if the place has a PolySurface representation).
The dict looks like :
{
'idSite' : int, //id of the Site
'nameSite' : string, //name of the Site
'idBuilding': int, //id of the Building
'nameBuilding': string, //name of the Building
'places : [
{
'id': int, //unique id
'names' : string[], //Names of the place, possibly empty,
'type': string, //in {'C'(orridor), 'S'(tairs), 'E'(levator), 'R'(oom)} ,
'surface' : list of [int, int] //list of every points composing the room, projected on the floor surface
'connectedFloors' : [
{
'id' : int,
'name' : string
},
{...}
]
},
{...}
]
}
Errors :
- If ID doesn't correspond to any registered floor : Return Error 404 "NotFoundHttpError".
- If ID has many occurence in the FloorRepository : Return Error 500 > The Database is corrupted.
/api/map/get_all_floors/
Return every sites, buildings and floors of the DB.
The json will look like :
[
{
'name': string, //name of Site 1
'id' : int, //id of Site 1
'buildings' : [
{
'name': string, //name of the first builing of Site 1
'id' : int, //its id
'floors' : [
{
'name': string, //name of the first floor of the building
'id' : int //its id
},
{
'name': string, //name of the second floor of the building
'id' : int //its id
},
{...}
]
},
{
'name': string, //name of the second builing of Site 1
'id' : int, //its id
'floors' : [...]
},
{...}
]
},
{
'name': string, //name of Site 2
'id' : int, //id of Site 2
'buildings' : [...]
},
{...}
]
/api/map/find_place_by_name/NAME
Return a list of dict representing all places with NAME.
Format of the dict :
[
{
'idPlace':int, //unique id of the place
'idSite': int, //id of the place Site
'idBuilding': int, //id of the place Building
'idFloors': int[] //list of every floorID the place is in
},
{...}
]
Notes :
- If NAME doesn't correspond to any registered place : Return an Empty list.
/api/map/get_site_name/ID
Return the name of the Site ID.
Errors :
- If ID doesn't correspond to any registered Site : Return Error 404 "NotFoundHttpError".
- If ID has many occurence in the SiteRepository : Return Error 500 > The Database is corrupted.
/api/map/get_building_name/ID
Return the name of the Building ID.
Errors :
- If ID doesn't correspond to any registered Building : Return Error 404 "NotFoundHttpError".
- If ID has many occurence in the BuildingRepository : Return Error 500 > The Database is corrupted.
/api/map/get_floor_name/ID
Return the name of the Floor ID.
Errors :
- If ID doesn't correspond to any registered Floor : Return Error 404 "NotFoundHttpError".
- If ID has many occurence in the FloorRepository : Return Error 500 > The Database is corrupted.
/api/map/show_place_info/ID
Return a dict with main pieces of informations of the place ID.
Format of the dict :
{
'idPlace': int,
'names': string[], // list of names for this place
'users': string[], // list of users' name (professors, etc)
'floors' : int[] // list of floorIds the place is connected.
}
Errors :
- If ID doesn't correspond to any registered place : Return Error 404 "NotFoundHttpError".
- If ID has many occurence in the PlaceRepository : Return Error 500 > The Database is corrupted.
/api/map/get_all_editions
Return a list of all editions currently pending. ie returns a table of dict, each representing en edition.
Each edition is a dict :
{
'id': int // id of the edition,
'mode': string, // could be add_place_name, del_place_name, add_room_user_name or del_room_user_name
'placeNames': string[], // list of names of the place
'placeId': string, // id of the place
'editorValue': string // the value to add or remove
}
Notes :
- If there is no pending edition : Return Empty list
- The strings in mode are transparent to the API so the given names are only an advice. The only rules is to set adequaly create_edition and the treatment of editions.
/api/map/create_edition/MODE/PLACEID/VALUE
Add an edition to the BDD MODE should be in {AddPlaceName ; DelPlaceName ; AddRoomUserName ; DelRoomUserName}. In fact it is transparent to the API and the mode is set by the frontend when it creates an edition.
Return 'added' if successful.
Errors :
- If PLACEID doesn't correspond to any registered place : Return Error 404 "NotFoundHttpError".
- If PLACEID has many occurence in the PlaceRepository : Return Error 500 > The Database is corrupted.
/api/map/remove_edition/ID
Remove the edition with ID from the Database. It should be called after successfully treating any edition to remove it from the pending editions. Warning: The edition proposal is lost as there is no log for now.
Return 'removed' if successful.
Errors :
- If ID doesn't correspond to any registered edition : Return Error 404 "NotFoundHttpError".
- If ID has many occurence in the EditionRepository : Return Error 500 > The Database is corrupted.
/api/map/del_place_name/PLACEID/NAME
Remove NAME from the place PLACEID. Warning: The name is lost as there is no log for now.
Return 'removed' if successful.
Errors :
- If (PLACEID,NAME) doesn't match any line of PlaceNameRepository ie the NAME is not registered for place PLACEID or this place doesn't exists : Return Error 404 "NotFoundHttpError".
Note :
- If (PLACEID,NAME) has many match in the PlaceNameRepository, it will only remove one of them. But it shouldn't happen as the API asset that the name isn't registered for this place when adding it.
/api/map/add_place_name/PLACEID/NAME
Add NAME to the place PLACEID.
Return 'added' if successful.
Errors :
- If PLACEID doesn't correspond to any registered place : Return Error 404 "NotFoundHttpError".
- If PLACEID has many occurence in the PlaceRepository : Return Error 500 > The Database is corrupted.
- If NAME is already registered as a name of place PLACEID : Return Error 412 "PreconditionFailedHttpException" > It's a Warning that is not fatal as the DB will have the desired names after the request (but I didn't manage to raise a warning with symfony so it's still an error)
/api/map/del_room_user_name/PLACEID/NAME
Remove NAME from the usernames using the place PLACEID. Warning: The name is lost as there is no log for now.
Return 'removed' if successful.
Errors :
- If (PLACEID,NAME) doesn't match any line of RoomUserNameRepository ie the NAME is not registered as a user for place PLACEID or this place doesn't exists : Return Error 404 "NotFoundHttpError".
Note :
- If (PLACEID,NAME) has many match in the RoomUserNameRepository, it will only remove one of them. But it shouldn't happen as the API asset that the username isn't registered for this place when adding it.
/api/map/add_room_user_name/PLACEID/NAME
Add NAME to the usernames using the place PLACEID.
Return 'added' if successful.
Errors :
- If PLACEID doesn't correspond to any registered place : Return Error 404 "NotFoundHttpError".
- If PLACEID has many occurence in the PlaceRepository : Return Error 500 > The Database is corrupted.
- If NAME is already registered as a username of place PLACEID : Return Error 412 "PreconditionFailedHttpException" > It's a Warning that is not fatal as the DB will have the desired names after the request (but I didn't manage to raise a warning with symfony so it's still an error)
/api/teapot
To test if the API is reachable in a fun way Return Error 418 'I'm a Teapot'