API/v1

De Wiki Biolovision
Révision datée du 5 juin 2014 à 02:35 par Admin (discussion | contributions) (Nouvelle page : == API documentation == === Atlas documents === :::'''Title''': <nowiki>Atlas documents</nowiki> :::'''URL''': <nowiki>/atlas_documents</nowiki> :::'''Description''': <nowiki>Atl...)
(diff) ← Version précédente | Voir la version actuelle (diff) | Version suivante → (diff)
Sauter à la navigation Sauter à la recherche

Sommaire

API documentation

Atlas documents

Title: Atlas documents
URL: /atlas_documents
Description: Atlas documents controller. Atlas documents are all documents associated to the atlas project, each document is associated with a grid, the document is visible to users that have the grid right.

Public Functions

List atlas documents
Title: List atlas documents
URL: /atlas_documents
Description: Returns the list of all atlas documents. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: id
1: filename
2: insert_date
3: id_grid
4: id_observer
5: is_published
6: grid_num
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /atlas_documents list all atlas documents. GET /atlas_documents with filename=test.txt, lists all atlas documents with a filename of test.txt. GET /atlas_documents with grid_num=5613, lists all atlas documents that are linked to the atlas grid 5913.
Return: A list of atlas documents.
Get a single atlas document
Title: Get a single atlas document
URL: /atlas_documents/%id%
Description: Get an atlas document of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /atlas_documents/5 retrieve atlas document of id 5.
Return: An atlas document of id %id%.

Entities

Title: Entities
URL: /entities
Description: Entities controller. An observer(user) can be linked to an entity. Observations can be posted as an entity rather than as an individual observer.

Public Functions

List Entities
Title: List Entities
URL: /entities
Description: Returns the list of all entities. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: short_name
1: full_name_french
2: address
3: url
4: description_french
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /entities list all entities.
Return: A list of entities.
Get a single entity
Title: Get a single entity
URL: /entities/%id%
Description: Get an entity of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /entities/5 retrieve entity of id 5.
Return: An entity of id %id%.

Export organizations controller.

Title: Export organizations controller.
URL: /export_organizations
Description: Export Organizations controller. Observers(users) can authorize different export organizations to export their data.

Public Functions

List export organizations
Title: List export organizations
URL: /export_organizations
Description: Returns the list of all export organizations. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: full_name
1: text_french
2: available
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /export_organizations lists all export organizations.
Return: A list of export organizations.
Get a single export organization
Title: Get a single export organization
URL: /export_organizations/%id%
Description: Get an export organization of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /entity/5 retrieve an export organization of id 5.
Return: An export organization of id %id%.

Families controller.

Title: Families controller.
URL: /families
Description: Families controller. Each species is part of both a taxonomic group (see taxo_groups controller) and a family. Example of families: Cuculidae, Equidae ...

Public Functions

List Families
Title: List Families
URL: /families
Description: Returns the list of all species families. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: id_taxo_group
1: latin_name
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /families list all families.
Return: A list of families.
Get a single family
Title: Get a single family
URL: /families/%id%
Description: Get a family of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /families/5 retrieve a family of id 5.
Return: A family of id %id%.

Grids controller

Title: Grids controller
URL: /grids
Description: Grids controller.

Public Functions

List Grids
Title: List Grids
URL: /grids
Description: Returns the list of all grids with limits. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: name
1: y_min
2: y_max
3: x_min
4: x_max
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /grids list all grids.
Return: A the list of grids.
Get a single grid
Title: Get a single grid
URL: /grids/%id%
Description: Get a grid of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /grids/5 retrieve grid of id 5.
Return: A grid of id %id%.

Local admin units controller.

Title: Local admin units controller.
URL: /local_admin_units
Description: Local admin units controller. Example of a local administrative unit: a commune.

Public Functions

List local admin units
Title: List local admin units
URL: /local_admin_units
Description: Returns the list of all local admin units. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: name
1: insee
2: id_canton
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /local_admin_units list all local admin units.
Return: A list of local admin units.
Search local admin units
Title: Search local admin units
URL: /local_admin_units/search
Description: Returns the list of all communes ordered by smaller size of text first.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
2: name
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: GET /local_admin_units/search with url param of name=[?] list all local admin unit named [?]. If we search for "abc", "abc" will be first result before "abcd" because "abc" is shorter.
Return: A list of local admin units.
Get a single local admin unit
Title: Get a single local admin unit
URL: /local_admin_units/%id%
Description: Get one local admin unit of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /local_admin_units/5 retrieve local admin unit of id 5.
Return: A local admin unit of id %id%.

Media Controller

Title: Media Controller
URL: /media
Description: Media controller. A media can be photos or sounds.

Public Functions

Observations Controller

Title: Observations Controller
URL: /observations
Description: Observations controller.

Public Functions

List Observations
Title: List Observations
URL: /observations
Description: Returns the list of all observations. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: id
1: id_taxo_group
2: id_species
3: id_place
4: id_observer
5: id_transmitter
6: id_form
7: id_grid
8: lat
9: lon
10: precision
11: date
12: date_reverse
13: year
14: day_number
15: estimation_code
16: total_number
17: flight_number
18: atlas_code
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /observations list all observations. GET /observations with id_species=%id_species% search for all observations with id_species=%id_species%. See optional parameters for more search options.
Return: json with the list of observations.
Get a single observation
Title: Get a single observation
URL: /observations/%id%
Description: Get an observation of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /observations/5 retrieve observation of id 5.
Return: An observation of id %id%.
Create an observation
Title: Create an observation
URL: /observations
Description: Create a new observation.
Method: POST
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload: {%json of observation%}
Possible Output Format:
Usage: POST /observations create a new observation using body payload. Example of body payload: { "data": { "sightings": [ { "date": { "@timestamp": "1358204400" }, "species": { "@id": "86" }, "observers": [ { "@id": "%replace by id_observer%", "coord_lat": "46.657314336776", "coord_lon": "6.8703200880124", "precision": "precise", "estimation_code": "EXACT_VALUE", "count": "6", "altitude": "800" } ] } ] } }
Return: success message in header, check http status code. 201 successful
Update an observations
Title: Update an observations
URL: /observations/%id%
Description: Update an observation.
Method: PUT
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload: {%json of observation%}
Possible Output Format:
Usage: PUT /observations/%id% update an observation using body payload. Check "create an observation" for body payload.
Return: success message in header, check http status code.
Delete an observations
Title: Delete an observations
URL: /observations/%id%
Description: Delete an observation of id %id%. Only observations of the current user can be deleted.
Method: DELETE
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
Usage: DELETE /observations/%id% delete an observation.
Return: success message in header, check http status code. 200 successful
Search an observation
Title: Search an observation
URL: /observations/search
Description: Search for an observation, same parameters than in online version can be used, parameters need to be provided in body payload.
Method: POST
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload: {%search parameters in json format: period_choice=%period_choice=enum(range, season, offset, all)%, date_from, date_to, season_from, season_to ,offset, entry_date, species_choice=%species_choice=enum(all, family, species, category)% specie, family, rarity, location_choice, territorial_unit=%territorial_unit=enum(all, territorial_unit, local_admin_unit, place, coord, grid)%, place, local_admin_unit, territorial_unit_ids, grid_id, coordinates, coordinates_list, altitude_min, altitude_max, atlas_code, comment, observer_id, observers_id_list, only_my_data, only_export, only_entity, only_exported, only_not_exported, only_need_validation, only_form, form, only_with_picture, only_with_sound, only_new, only_death, only_echouage, only_stoc, project, only_with_ring, only_age_sex, chiro_acoustic, chiro_bio, chiro_telemetric, chiro_view, chiro_trace, only_colony, only_colony_extended, rarity_committee %}
Possible Output Format:
0: json
Usage: POST /observations/search search an observation using body payload. Example of body payload: {"period_choice":"range","date_from":"1.1.2013","date_to":"15.1.2013","species_choice":"all"}
Return: list of observations.
Search closest observations
Title: Search closest observations
URL: /observations/around_me
Description: Search for last observations that are near the coordinate given (4 km area, 5 last days). If no coordinate is given default position from observer will be used.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: lat
1: lon
Body Payload:
Possible Output Format:
0: json
Usage: POST /observations/around_me with lat=%lat% and lon=%lon% search last 5 days observations in a close area of 50 km from %lat%, %lon%.
Return: list of observations.
Search last observations
Title: Search last observations
URL: /observations/last
Description: Search for last observations (50 km, 5 days). If no coordinate is given default position from observer will be used.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: lat
1: lon
Body Payload:
Possible Output Format:
0: json
Usage: POST /observations/last with lat=%lat% and lon=%lon% search last 5 days observations in area of 50 km from %lat%, %lon%.
Return: list of observations.
Search rare observations
Title: Search rare observations
URL: /observations/rare
Description: Search for last rare observations (100 km, 7 days). If no coordinate is given default position from observer will be used.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: lat
1: lon
Body Payload:
Possible Output Format:
0: json
Usage: POST /observations/rare with lat=%lat% and lon=%lon% search last 7 days observations in area of 100 km from %lat%, %lon%.
Return: list of observations.
Search my observations
Title: Search my observations
URL: /observations/my
Description: Search for all observations of observer (user_email used).
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: POST /observations/my search all observations from current observer (user_email).
Return: list of observations.
Search observations from a list of observers
Title: Search observations from a list of observers
URL: /observations/observers_list
Description: Search for all observations that have been done by a given list of observers.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
2: date_from
3: date_to
4: observers_id_list
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: POST /observations/observers_list with date_from=01.01.2014, date_to=01.02.2014, observers_id_list=1,2,3 search all observations from observers with id 1,2,3.
Return: list of observations.
Search observations from a list of coordinates
Title: Search observations from a list of coordinates
URL: /observations/coordinates_list
Description: Search for all observations of given coordinates list.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
2: date_from
3: date_to
4: coordinates_list
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: GET /observations/coordinates_list with coordinates_list=%lat_1%:%lon_1%,%lat_2%:%lon_2%
Return: list of observations.
Search resources linked to an observation
Title: Search resources linked to an observation
URL: /observations/%observation_id%/%resource%
Description: Search for all resources linked to the %observation_id% observation. Possible resources are : photos
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: GET /observations/1/photos search all photos linked to observation with id 1.
Return: list of resources.
Create a new resources for an observation
Title: Create a new resources for an observation
URL: /observations/%observation_id%/%resource%
Description: Creates a new resource and link it to an observation with %observation_id%, %resource% is the type of resource. Possible resources are : photos.
Method: POST
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: POST /observations/1/photos create a new resource using file input as content.
Return: New resource created.

Observers

Title: Observers
URL: /observers
Description: Observers controller. Observers are users of the current website.

Public Functions

Current Observers
Title: Current Observers
URL: /observers/current
Description: Returns the currently logged-in users data. Search on optional parameters can also be done.
Method:
0: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: name
1: surname
2: email
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /observers/current
Return: list of observers

Places controller

Title: Places controller
URL: /places
Description: Places controller. Places are linked to the local admin units on which they are contained. On some websites places can represent directly a local admin unit.

Public Functions

List places
Title: List places
URL: /places
Description: Returns the list of all places. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: id_commune
1: name
2: id_region
3: place_type
4: coord_lon
5: coord_lat
6: find_closest_place
7: get_hidden
8: pick_limit
Body Payload:
Possible Output Format:
0: json
Usage: GET /places list all places. GET /places with find_closest_place=1 and coord_lat=%lat% and coord_lon=%lon% search for the nearest place from the coordinate.
Return: A list of places.
Get a single place
Title: Get a single place
URL: /places/%id%
Description: Get a place of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /places/5 retrieve entity of id 5.
Return: A place of id %id%.

Species Controller

Title: Species Controller
URL: /species
Description: Species controller.

Public Functions

List Species
Title: List Species
URL: /species
Description: Returns the list of all species. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: id
1: rarity
2: french_name
3: german_name
4: english_name
5: spanish_name
6: dutch_name
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /species list all species.
Return: json with the list of species.
Get a single species
Title: Get a single species
URL: /species/%id%
Description: Get a species of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /species/5 retrieve species of id 5.
Return: A species of id %id%.

Taxo groups

Title: Taxo groups
URL: /taxo_groups
Description: Taxo groups controller. Each species has a family and a taxo group. Example of taxo groups: birds, sea mammals.

Public Functions

List taxo groups
Title: List taxo groups
URL: /taxo_groups
Description: Returns the list of all taxo groups. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /taxo_groups list all taxo groups. GET /taxo_groups/%id% get one taxo group of %id%
Return: A list of taxo groups.
Get a single taxo group
Title: Get a single taxo group
URL: /taxo_groups/%id%
Description: Get a taxo group of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /taxo_groups/5 retrieve taxo_groups of id 5.
Return: A taxo group of id %id%.
Create new taxo group
Title: Create new taxo group
URL:
0: /taxo_groups
Description: Create a new taxo group with id,name and access_mode.
Method: POST
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload: {"id":%id%,"name":%name%,"access_mode":%access_mode%}
Possible Output Format:
0: json
Usage: POST /taxo_groups with body payload : {"id":62,"name":"TAXO_TEST","access_mode":"full"} access_mode can be "full", "limited", "readonly", "none"
Return: success message.
Update a taxo group
Title: Update a taxo group
URL:
0: /taxo_groups/%id%
Description: Update a taxo group, change access_mode.
Method: PUT
URL Params :
Required:
0: user_pw
1: user_email
2: access_mode
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: PUT /taxo_groups/%id% with access_mode="limited", access_mode can be "full", "limited", "readonly", "none"
Return: success message.
Delete a taxo group
Title: Delete a taxo group
URL:
0: /taxo_groups/%id%
Description: Delete a taxo group.
Method: DELETE
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
Usage: DELETE /taxo_groups/%id%
Return: success message.

Taxo groups by website

Title: Taxo groups by website
URL: /taxo_website
Description: Taxo groups by website controller.

Public Functions

List links between taxo groups and websites
Title: List links between taxo groups and websites
URL: /taxo_website
Description: Returns the list of all taxo groups by website.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /taxo_website list all taxo groups by websites.
Return: A list of links between taxo groups and websites.
Get a single link between taxo groups and websites
Title: Get a single link between taxo groups and websites
URL: /taxo_website/%id%
Description: Get a link between a taxo group and a website of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /taxo_website/5 retrieve a link between a taxo group and a website of id 5.
Return: A link between a taxo group and a website.

Territorial Units Controller.

Title: Territorial Units Controller.
URL: /territorial_units
Description: Territorial Units controller. A territorial unit is an area that contains the local admin units (see local admin units controller). Example of territorial unit: Canton, Département, Kreise

Public Functions

List Territorial Units
Title: List Territorial Units
URL: /territorial_units
Description: Returns the list of all local territorial units. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: id_country
1: name
2: short_name
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /territorial_units list all local admin units. GET /territorial_units with name=%name% search for all territorial units with name=%name%.
Return: A list of local territorial units.
Get a single territorial unit
Title: Get a single territorial unit
URL: /territorial_units/%id%
Description: Get a territorial unit of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /territorial_units/5 retrieve a territorial unit of id 5.
Return: A territorial unit.

Validations controller

Title: Validations controller
URL: /validations
Description: Validations controller. A validation is composed of a start date, a stop date, a specie and a validation committee.

Public Functions

List Validations
Title: List Validations
URL: /validations
Description: Returns the list of all validations. Search on optional parameters can also be done.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
0: committee
1: date_start
2: date_stop
3: id_species
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /validations list all validations.
Return: A list of validations.
Get a single validation
Title: Get a single validation
URL: /validations/%id%
Description: Get a validation of id %id%.
Method: GET
URL Params :
Required:
0: user_pw
1: user_email
Optional:
Body Payload:
Possible Output Format:
0: json
1: xml
Usage: GET /validations/5 retrieve a validation of id 5.
Return: A validation.