Esta página describe el comportamiento IPA RESTful de este sitio web libre y abierto

Con el fin de poder ejecutar las operaciones de escritura, primero tiene que autenticar y obtener una clave IPA en su configuración de perfil

Esta clave debe ser proporcionada en cada llamada en el X-API-KEY encabezado HTTP.

Las llamadas IPA están sujetas a los mismos permisos que la interfaz web.

Por ejemplo, es necesario formar parte de la organización para modificar uno de sus conjuntos de datos.

Algunos métodos están paginados y seguidos siempre por el mismo patrón. La lista de objetos está envuelta en un Page objeto.

Usted no tiene que calcular las páginas anteriores y siguientes pues las URLs están disponibles en la respuesta abajo de los atributos de las previous_page y next_page. Estas se establecerán en null si no hay una página anterior y/o siguiente.

Ejemplo:

{
    "data": [{...}, {...}],
    "page": 1,
    "page_size": 20,
    "total": 43,
    "next_page": "http://www.data.gouv.fr/api/endpoint/?page=2",
    "previous_page": null
}

Todos los ejemplos usan las funciones httpie y jq para propósitos de legibilidad. Sin embargo, no necesita usar estas herramientas en su código, sólo son ayudas para entender mejor la API.

Verificando que httpie está funcionando

Una vez que httpie se encuentra instalado, puede verificar que funciona correctamente escribiendo este comando en su ventanilla:

$ http 'https://www.data.gouv.fr/api/1/organizations/?page_size=1'

Debería devolver algo de este estilo:


HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
... LOTS OF HEADERS ...

{
    "data": [
        {

            ... LOTS OF DATA ...

            "name": "Premier ministre",
            "page": "https://www.data.gouv.fr/fr/organizations/premier-ministre/",
            "slug": "premier-ministre",
            "uri": "https://www.data.gouv.fr/api/1/organizations/premier-ministre/",
            "url": null
        }
    ],
    "next_page": "https://www.data.gouv.fr/api/1/organizations/?page=2&page_size=1",
    "page": 1,
    "page_size": 1,
    "previous_page": null,
    "total": 529
}

Esto es muy largo y no necesitamos toda esta información aún. Por eso utilizamos jq.

Verificando que jq funciona

Una vez que jq se encuentra instalado, puede verificar que funciona como correctamente escribiendo este comando en su ventanilla:

$ http 'https://www.data.gouv.fr/api/1/organizations/?page_size=1' | jq '.data[].name'

Debería devolver algo de este estilo:

"Premier ministre"

Esto es definitivamente mejor! Ahora que estamos seguros de que funciona correctamente, vamos a acortar un poco la línea de comando:

$ export API="https://www.data.gouv.fr/api/1/"

El colando anterior es ahora equivalente al más legible (no se olvide de las comillas) :

$ http $API'organizations/?page_size=1' | jq '.data[].name'

Es un buen comienzo, ahora vamos a concentrarnos en la API misma. No lo sabemos todavía, pero ya hemos alcanzado nuestra primera organización:

Navegando y recuperando datos

Puede recuperar una lista de organizaciones (filtrada o no) o una sola oorganización. Cuando llega al punto final, el tamaño de página por defecto es 20. Vamos a tomar las primeras 20 organizaciones a partir de la API:

$ http $API'organizations/' | jq '.data[].name'

"Premier ministre"
"Eurostat"
"Institut National de la Statistique et des Etudes Economiques (INSEE)"
"Ministère de l'Intérieur"
"Ministère des finances et des comptes publics"
"Ministère de la Culture et de la Communication"
"Education Nationale"
"Institut National de l'Information Géographique et Forestière"
"Ministère des Affaires sociales, de la Santé et des Droits des femmes"
"Région Île-de-France"
"Enseignement supérieur et Recherche"
"Caisse nationale de l'assurance maladie des travailleurs salariés"
"Mairie de Paris"
"La Poste"
"Etalab"
"Ministère de l'Ecologie du Développement Durable et de l'Energie"
"Ministère de l'Agriculture, de l'Agroalimentaire et de la Forêt"
"Ministère des Affaires Etrangères et du Développement International (MAEDI)"
"Ministère de la ville, de la jeunesse et des sports"
"Ministère du travail, de l'emploi et du dialogue social"

Es muy bueno tener esta lista pero que pasa si queremos pasar a través de estas organizaciones? Vamos a tomar las primero 5 organizaciones URIs:

$ http $API'organizations/?page_size=5' | jq '.data[].uri'

"https://www.data.gouv.fr/api/1/organizations/premier-ministre/"
"https://www.data.gouv.fr/api/1/organizations/eurostat/"
"https://www.data.gouv.fr/api/1/organizations/institut-national-de-la-statistique-et-des-etudes-economiques-insee/"
"https://www.data.gouv.fr/api/1/organizations/ministere-de-l-interieur/"
"https://www.data.gouv.fr/api/1/organizations/ministere-des-finances-et-des-comptes-publics/"

Ahora vamos a poder recuperar una organización única, gracias a la URI:

$ http $API'organizations/premier-ministre/' | jq '.'

Hay demasiados datos que procesar. Vamos a refinar los datos, si sólo queremos métricas:

$ http $API'organizations/premier-ministre/' | jq '.metrics'

{
  "dataset_views": 16345,
  "datasets": 178,
  "followers": 79,
  "members": 16,
  "nb_hits": 0,
  "nb_uniq_visitors": 0,
  "nb_visits": 0,
  "permitted_reuses": 82,
  "resource_downloads": 4316,
  "reuse_views": 257,
  "reuses": 3,
  "views": 699
}

O tal vez sólo el nombre de los miembros de esa organización:

$ http $API'organizations/premier-ministre/' | jq '.members[].user.last_name'

"Javelle"
"Pelletier"
"des victimes de spoliations"
"Mestre"
"BENVENUTO"
""
"Tales"
"Saint-Aubin "
"Biafora"
"Cottin"
"ROGER"
"des retraites (Premier ministre)"
"Modestine"
"Roullier"
"Roullier"
"Chignard"

Depende de usted recuperar los datos que importan para su proyecto. No dude en leer jq's tutorial y manual si quiere navegar por la API a través de la línea de comandos en profundidad.

Modificando y borrando los datos

Cuidado, está entrando en una zona de peligro. Las modificaciones o supresiones con la API son definitivas y no proveemos ninguna instancia para testearlas previo a la ejecución (por el momento). Sea consciente de esta responsabilidad antes de utilizar esta gran potencia.

Si intenta modificar un archivo sin una autentificación, un 401 aparecerá:

$ http PUT $API'organizations/premier-ministre/'

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Unauthorized",
    "status": 401
}

Necesita especificar su llave API (ver arriba) y usar el encabezado X-API-KEY HTTP. Si intenta modificar un recurso sobre el cual no tiene control, un 400 aparecerá:

$ http PUT $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Invalid API Key",
    "status": 401
}

Este es el mensaje que aparecerá si usted especificó la llave API incorrecta. Existe otro potencial mensaje de error que puede encontrar:


HTTP/1.1 403 FORBIDDEN
... LOTS OF HEADERS ...

{
    "message": "You do not have the permission to modify that object.",
    "status": 403
}

Ocurre si intenta acceder a un recurso que no puede editar con sus credenciales. Si su llave no es válida algo como esto debe aparecer:


HTTP/1.1 200 OK
... LOTS OF HEADERS ...

{
    ...
}

Pero no cambié nada! Esto es perfectamente normal, nos olvidamos de especificar los datos correctos para enviar al servidor.

$ http PUT $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here name="Premier ministre fr" description="Administration du Premier ministre." | jq '{name: .name, description: .description}'

{
  "name": "Premier ministre fr",
  "description": "Administration du Premier ministre."
}

El recurso fue modificado con nuevos valores. Finalmente, puede borrar un recurso con el verbo HTTP apropriado (cuidado, no se puede volver atrás usando la API por el momento):

$ http DELETE $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here

HTTP/1.0 204 NO CONTENT
... LOTS OF HEADERS ...

Una vez que lo hizo, puede verificar que funciona sacando un GET contra las URI previas:

$ http GET $API'organizations/premier-ministre/'

HTTP/1.0 410 GONE
... LOTS OF HEADERS ...

{
    "message": "Organization has been deleted",
    "status": 410
}

Por favor consulte las documentaciones de referencia debajo para mayores interacciones con la API o consulte!