6.6 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 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).
Each place is a dict :
{
'id': int, //unique id
'names' : string[] //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
}
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/find_place_by_name/NAME
Return a dict representing the place with NAME.
Format of the dict :
{
'idPlace':int, //unique id of the place
'idFloors': int[] // list of every floorID the place is in
}
Errors :
- If NAME doesn't correspond to any registered place : Return Error 404 "NotFoundHttpError".
- If NAME has many occurence in the PlaceNameRepository : Return Error 500 "UnprocessableEntityHttpException" > The API can't decide which place should be provided.
/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)
}
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.
Each place is a dict :
{
'id': int // id of the edition,
'mode': string // should be AddName, RemoveName, AddUser or RemoveUser
'placeNames': string[] // list of names of the place
'placeId': string // id of the place
'editorValue': string // the value to add or remove
}
Errors :
- If there is no pending edition : Return Error 404 "NotFoundHttpError" > It's a Warning that is not fatal (but I didn't manage to raise a warning with symfony so it's still an error)
/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 500 "ValueError" > It's a Warning that is not fatal (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 500 "ValueError" > It's a Warning that is not fatal (but I didn't manage to raise a warning with symfony so it's still an error)