Commit 73bb4fa6 authored by Blaise de Carné 's avatar Blaise de Carné

Initial commit

parents
Pipeline #49315 passed with stage
in 14 seconds
/.php_cs.cache
/.phpunit
/phpunit.xml
/composer.lock
/composer.phar
/vendor/
/.idea/
/var/
/bin/
\ No newline at end of file
image: alpine:latest
pages:
stage: deploy
script:
- cp -rp docs public
artifacts:
paths:
- public
only:
- master
<?php
/**
* This file is part of the DATAtourisme project.
*
* @author Conjecto <contact@conjecto.com>
*
* For the full copyright and license information, please view the LICENSE file that was distributed with this source code.
*/
$finder = PhpCsFixer\Finder::create()
->exclude('var')
->notName('*.twig')
->in(array(__DIR__));
return PhpCsFixer\Config::create()
->setRules(array(
'@Symfony' => true
))
->setFinder($finder);
\ No newline at end of file
# Changelog
Tous les changements notables apportés à ce projet seront documentés dans ce fichier.
Le format est basé sur [Keep a Changelog](http://keepachangelog.com/fr/1.0.0/)
et ce projet adhère à [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
## [1.0.0] - 2018-04-24
### Ajouts
- Code source initial
- Documentation
MIT License
Copyright (c) 2018 DATAtourisme
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
\ No newline at end of file
<p align="center">
<a href="https://www.datatourisme.gouv.fr" target="_blank">
<img alt="DATAtourisme" src="./docs/_media/logo.png">
</a>
</p>
<p align="center">
La plateforme <strong>OPEN DATA</strong> de l'information touristique
</p>
<p align="center"><a href="https://www.datatourisme.gouv.fr/">https://www.datatourisme.gouv.fr</a></p>
# API diffuseur
* Librairie PHP pour interroger simplement les données issues de DATAtourisme
* Compatible avec les flux sémantiques téléchargés sur la [plateforme diffuseur](https://diffuseur.datatourisme.gouv.fr)
* Compatible avec [GraphQL](https://graphql.org) et [l'ensemble de son éco-système](https://github.com/chentsulin/awesome-graphql)
* Extensible aux données complémentaires
## Démarrage rapide
Vous pouvez directement consulter la section [Démarrage rapide](https://datatourisme.frama.io/api/#/start/getting_started) de la documentation pour commencer à utiliser l'API.
## Liens
* [Documentation](https://datatourisme.frama.io/api)
* [Plateforme diffuseur](https://diffuseur.datatourisme.gouv.fr)
* Centre de support
* [Environnement full-stack Docker](https://framagit.org/datatourisme/docker-stack)
## Contribuer
* Faites un fork !
* `git checkout -b feature/my-new-feature`
* `git commit -am 'Add some feature'`
* `git push origin feature/my-new-feature`
* Soumettez votre pull request
## License
MIT License
\ No newline at end of file
{
"name": "datatourisme/api",
"license": "MIT",
"keywords": ["graphql","datatourisme","api","sparql","opendata"],
"type": "library",
"version": "1.0.0",
"homepage": "https://www.datatourisme.gouv.fr",
"authors": [
{
"name": "Conjecto",
"email": "contact@conjecto.com"
}
],
"support": {
"docs": "https://datatourisme.frama.io/api/",
"source": "https://framagit.org/datatourisme/api"
},
"autoload": {
"psr-4": {
"Datatourisme\\Api\\": "src/",
"Tests\\Datatourisme\\Api\\": "tests/"
}
},
"autoload-dev": {
"psr-4": {
"Tests\\": "tests/"
}
},
"require": {
"php": ">=7.0.0",
"Youshido/graphql": "^1.0",
"symfony/config": "^4.0",
"symfony/yaml": "^4.0",
"twig/twig": "^2.4",
"easyrdf/easyrdf": "^0.9.1"
},
"require-dev": {
"phpunit/phpunit": "^7.1",
"phpunit/php-invoker": "^2.0",
"phpunit/php-code-coverage": "^6.0",
"friendsofphp/php-cs-fixer": "^2.0",
"symfony/var-dumper": "^4.0"
},
"scripts": {
"clean": "vendor/bin/php-cs-fixer fix -v --using-cache=no",
"generate_doc": [
"graphql-markdown http://localhost:8080 > docs/api/reference.md",
"sed -i -e \"s/# Schema Types/# Référence/g\" docs/api/reference.md",
"sed -i -e \"s/href=\\\"#/href=\\\"#\\/schema?id=/g\" docs/api/reference.md",
"sed -i -e \"s/id=pointofinterest_sort/id=pointofinterest/g\" docs/api/reference.md",
"sed -i -e \"s/id=pointofinterest_filter/id=pointofinterest/g\" docs/api/reference.md",
"sed -i -e \"s/<th align=\\\"right\\\">Argument<\\\/th>//g\" docs/api/reference.md",
"sed -i -e \"s/<th align=\\\"left\\\">Field<\\\/th>/<th align=\\\"left\\\" colspan=\\\"2\\\">Field<\\\/th>/g\" docs/api/reference.md"
]
}
}
version: "3"
services:
blazegraph:
image: conjecto/blazegraph
ports:
- 9999:9999
volumes:
- ./tests/RWStore.properties:/docker-entrypoint-initdb.d/kb/RWStore.properties
- ./tests/dataset.ttl:/docker-entrypoint-initdb.d/kb/data/dataset.ttl
virtuoso:
image: tenforce/virtuoso:1.3.1-virtuoso7.2.2
ports:
- 8890:8890
volumes:
- ./tests/dataset.ttl:/data/toLoad/dataset.ttl
\ No newline at end of file
<!-- _navbar.md -->
* Commencer
* [Le projet DATAtourisme](start/project.md)
* [Principes de l'API](start/principles.md)
* [Démarrage rapide](start/getting_started.md)
* Utilisation de l'API
* [Champs](api/fields.md)
* [Arguments](api/arguments.md)
* [Filtres](api/filters/filters.md)
* [Référence complète](api/reference.md)
* Guide
* [Resolver](guide/resolver.md)
* [Point d'accès GraphQL](guide/endpoint.md)
\ No newline at end of file
# Arguments
La requête **poi** accepte plusieurs paramètres destinés à modifier la sélection des résultats retournés :
```graphql
{
poi(
# <- arguments de la requête
) {
# ...
}
}
```
Voici la liste des arguments disponibles :
```graphql
{
poi(
uri: "http://...", # <- Spécifie un identifiant de POI
size: 10, # <- Limite le nombre de résultats par page
from: 0, # <- Précise le début de page
filters: [
# ... <- Liste des filtres à appliquer pour sélectionner les POI
],
sort: [
# ... <- Liste des règles de tri des résultats
]
) {
# ...
}
}
```
?> **Note** : L'ordre des arguments n'a pas d'importance.
## uri
L'argument **uri** permet de demander un POI en particulier, en précisant son URI. Le POI en question sera alors renvoyé
par l'API en respectant la structure des champs demandés dans le corps de la requête.
** Exemple **
```graphql
{
poi(
uri: "https://data.datatourisme.gouv.fr/31/27684064-5142-3a1f-ac20-9c1b656732c7"
)
{
results{
dc_identifier
}
}
}
```
Cette requête extrait tous les identifiants des **POI** dont l'URI est "https://data.datatourisme.gouv.fr/31/27684064-5142-3a1f-ac20-9c1b656732c7".
** Résultat **
```json
{
"data": {
"poi": {
"results": [
{
"dc_identifier": [
"TFO267549641513"
]
}
]
}
}
}
```
## size, from
Les arguments **limit** et **from** permettent de gérer la pagination de la requête en limitant le nombre de résultats renvoyés par la requête et en se positionnant dans ces résultats.
?> Par défaut, si le champ **size** n'est pas spécifié, **le nombre de résultats renvoyés est de 10**.
```graphql
{
poi(
from: <position_résultats>,
size: <nombre_de_résultats>
)
{
# ...
}
}
```
** Exemple **
```graphql
{
poi(
from: 5,
size: 2
)
{
results {
dc_identifier
}
}
}
```
Cette requête extrait `2` identifiants de **POI** à partir du `cinquième` résultat renvoyé par la requête.
** Résultat **
```json
{
"data": {
"poi": {
"results": [
{
"dc_identifier": [
"TFO311775817951"
]
},
{
"dc_identifier": [
"TFO309273189469"
]
}
]
}
}
}
```
## filters
L'argument **filters** permet de préciser une liste des filtres destinés à limiter les résultats en fonction de critères.
** Exemple **
```graphql
{
poi(
filters: [
{
allowedPersons: {
_eq: 30
}
}
]
)
{
results{
_uri
}
}
}
```
La requête est ici limitée aux POI dont le nombre de personnes autorisées est égal à 30.
Le fonctionnement et la liste des filtres sont détaillés sur [la page dédiée aux filtres](api/filters/filters.md).
## sort
**sort** permet de trier les résultats en fonction d'une ou plusieurs propriétés.
```graphql
{
poi(
sort:[
{ <propriété>: { order: <ordre de tri> } }
]
)
{
# ...
}
}
```
L'**ordre de tri** peut être '**desc**' ou '**asc**'. Par défaut, l'ordre est aléatoire.
```graphql
{
poi(
sort:[
{ <propriété>: { order: "desc" } },
]
)
{
# ...
}
}
```
Les propriétés peuvent être atteintes en intégrant la hiérarchie dans le tri
```graphql
{
poi(
sort:[
{ <propriété1> : {<propriété2> : { order: <ordre de tri> } } }
]
)
{
# ...
}
}
```
Les tris peuvent être cumulés simplement :
```graphql
{
poi(
sort:[
{ <propriété1>: { order: "desc" } },
{ <propriété2>: { order: "asc" } }
]
)
{
# ...
}
}
```
** Exemple **
```graphql
{
poi(
sort: [{ allowedPersons: { order: "desc" }}]
)
{
total
results {
dc_identifier
}
}
}
```
Cette requête extrait tous les identifiants des **POI** par ordre décroissant du nombre de personnes autorisées.
** Résultat **
```json
{
"data": {
"poi": {
"total": 3,
"results": [
{
"allowedPersons": [20]
},
{
"allowedPersons": [20]
},
{
"allowedPersons": [15]
}
]
}
}
}
```
\ No newline at end of file
# Champs
Le principe essentiel de GraphQL est d'adapter la réponse aux champs demandés par l'utilisateur dans le corps de la
requête :
```graphql
{
poi {
# ... <- corps de la requête
}
}
```
Voici la liste des champs disponibles :
```graphql
{
poi {
total # <- nombre total de résultats
results {
# ... <- Champs et sous-champs d'un POI
}
query # <- requête SPARQL générée et exécutée par l'API
}
}
```
C'est dans le champ **results** que l'utilisateur décrit précisément la structure des POI qu'il souhaite récupérer.
Cette structure doit respecter le format de l'ontologie.
L'[introspection GraphQL](http://graphql.org/learn/introspection/) vous permet de connaître précisément les champs et
sous-champs disponibles. Vous pouvez également consulter la [référence GraphQL](api/reference.md) de l'API, notamment
pour connaître la liste des champs d'un POI : [PointOfInterest](api/reference.md#pointofinterest).
?> **Note sur les namespaces RDF :** Les conventions RDF imposent le signe `:` entre le *prefix* du namespace et sa propriété ;
la spécification GraphQL n'autorisant pas cette notation, l'API DATAtourisme remplace le double point par un `_`.
Exemple: `rdfs:label` devient `rdfs_label`.
** Exemple **
```graphql
{
poi {
total
results {
_uri # <- Identifiant du POI
rdfs_label # <- Nom du POI
hasDescription {
shortDescription # <- Description du POI
}
}
}
}
```
** Résultat **
```json
{
"data": {
"poi": {
"total": 1308,
"results": [
{
"_uri": "https://data.datatourisme.gouv.fr/21/5430055a-2d35-3ce7-adc9-ebecb9f5cbfd",
"rdfs_label": ["Jouer aux échecs"],
"hasDescription": [{
"shortDescription": [
"Rendez-vous le 1er et le 3ème vendredi du mois à la maison des Associations, cours apprentissage, perfectionnement, rencontres amicales, tournois."
]
}]
},
{
"_uri": "https://data.datatourisme.gouv.fr/21/ce824246-dd4f-3f08-ab90-974a409f67d6",
"rdfs_label": ["Le sens de la fête"],
"hasDescription": [{
"shortDescription": [
"Comédie de Eric Toledano et Olivier Nakache. Avec Jean-Pierre Bacri, Gilles Lellouche, Eye Haidara."
]
}
]},
{
"_uri": "https://data.datatourisme.gouv.fr/31/00024f0a-74b7-34fd-80f0-eec5cbf61189",
"rdfs_label": ["Randonnée"],
"hasDescription": [{
"shortDescription": [
"Randonnée par les Randonneurs du Montet"
]
}]
}
]
}
}
}
```
# _and
**_and** réalise une opération logique **AND** sur un tableau d'expressions.
```graphql
{
poi(
filters: [
{ _and : [
{ <expression1> },
{ <expression2> }
]
}
]
)
{
results {
<propriété_extraite>
}
}
}
```
### Notation alternative
Une notation équivalente à la précédente est :
```graphql
{
poi(
filters: [
{ <expression1> },
{ <expression2> }
]
)
{
results {
<propriété_extraite>
}
}
}
```
### Exemples ###
```graphql
{
poi(
filters: [
{ _and : [
{hasDescription: {shortDescription: {_text: "trop"}}},
{rdf_type: {_eq: "http://test"}}
]
}
]
)
{
total,
results {
dc_identifier
}
}
}
```
Cette requête extraira tous les identifiants des **POI** dont la ressource est de type "http://test" et dont la description contient **"trop"**. Le résultat sera de ce type :
```json
{
"data": {
"poi": {
"results": [
{
"dc_identifier": [
"TFO308495934640"
]
}
]
}
}
}
```
\ No newline at end of file
# _eq
Détermine une condition d'égalité. L'opérateur **_eq** extrait les POI dont la propriété visée est égale à la valeur fournie.
```graphql
{
poi(
filters: [
{ <propriété>: {_eq: <valeur>} }
]
)
{
results {
<propriété_extraite>
}
}
}
```
### Comportement ###
- Egalité valeur de type scalaire :
l'égalité peut porter sur une valeur de type entier, réel, chaîne, booléen...
- Egalité valeur de type ressource :
l'égalité peut porter sur un **POI**, une personne, une adresse...
### Exemples ###