Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Bug #1466 - Make API documentation country agnostic #1542

Merged
merged 1 commit into from
Mar 27, 2018
Merged

Bug #1466 - Make API documentation country agnostic #1542

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
112 changes: 52 additions & 60 deletions udata/templates/apidoc.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ <h2>{{ _('Pagination') }}</h2>
"page": 1,
"page_size": 20,
"total": 43,
"next_page": "http://{{config.SERVER_NAME}}/api/endpoint/?page=2",
"next_page": "https://{{config.SERVER_NAME}}/api/endpoint/?page=2",
"previous_page": null
}</code></pre>
</div>
Expand All @@ -99,7 +99,7 @@ <h3>{% trans %}Verifying that httpie is working{% endtrans %}</h3>
<p>{% trans %}Once httpie is installed, you can verify that it works as expected by typing that command in your shell:
{% endtrans %}</p>

<pre><code class="json">$ http 'https://www.data.gouv.fr/api/1/organizations/?page_size=1'</code></pre>
<pre><code class="json">$ http 'https://{{config.SERVER_NAME}}/api/1/organizations/?page_size=1'</code></pre>

<p>{% trans %}It should return something in this vein:
{% endtrans %}</p>
Expand All @@ -115,14 +115,14 @@ <h3>{% trans %}Verifying that httpie is working{% endtrans %}</h3>

... 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/",
"name": "Organization Name",
"page": "https://{{config.SERVER_NAME}}/organizations/organization-name/",
"slug": "organization-name",
"uri": "https://{{config.SERVER_NAME}}/api/1/organizations/organization-name/",
"url": null
}
],
"next_page": "https://www.data.gouv.fr/api/1/organizations/?page=2&page_size=1",
"next_page": "https://{{config.SERVER_NAME}}/api/1/organizations/?page=2&page_size=1",
"page": 1,
"page_size": 1,
"previous_page": null,
Expand All @@ -138,17 +138,17 @@ <h3>{% trans %}Verifying that jq is working{% endtrans %}</h3>
<p>{% trans %}Once jq is installed, you can verify that it works as expected by typing that command in your shell:
{% endtrans %}</p>

<pre><code class="json">$ http 'https://www.data.gouv.fr/api/1/organizations/?page_size=1' | jq '.data[].name'</code></pre>
<pre><code class="json">$ http 'https://{{config.SERVER_NAME}}/api/1/organizations/?page_size=1' | jq '.data[].name'</code></pre>

<p>{% trans %}It should return something in this vein:
{% endtrans %}</p>

<pre><code class="json">"Premier ministre"</code></pre>
<pre><code class="json">"Organization Name"</code></pre>

<p>{% trans %}That's definitely better! Now that we're sure that it works as expected, let's shorten a bit the command line:
{% endtrans %}</p>

<pre><code class="json">$ export API="https://www.data.gouv.fr/api/1/"</code></pre>
<pre><code class="json">$ export API="https://{{config.SERVER_NAME}}/api/1/"</code></pre>

<p>{% trans %}The previous command is now equivalent to the more readable (don't forget the quotes):
{% endtrans %}</p>
Expand All @@ -167,26 +167,18 @@ <h3>{% trans %}Browsing and retrieving data{% endtrans %}</h3>
<pre><code class="json">$ http $API'organizations/' | jq '.data[].name'</code></pre>

<pre><code class="json">
"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"
"Organization name 1"
"Organization name 2"
"Organization name 3"
"Organization name 4"
"Organization name 5"
"Organization name 6"
"Organization name 7"
"Organization name 8"
"Organization name 9"
"Organization name 10"
...
"Organization name X"
</code></pre>

<p>{% trans %}That list is great to have but what if we want to walk through returned organizations? Let's fetch the first 5 organizations URIs:
Expand All @@ -195,22 +187,22 @@ <h3>{% trans %}Browsing and retrieving data{% endtrans %}</h3>
<pre><code class="json">$ http $API'organizations/?page_size=5' | jq '.data[].uri'</code></pre>

<pre><code class="json">
"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/"
"https://{{config.SERVER_NAME}}/api/1/organizations/organization-uri-1/"
"https://{{config.SERVER_NAME}}/api/1/organizations/organization-uri-2/"
"https://{{config.SERVER_NAME}}/api/1/organizations/organization-uri-3/"
"https://{{config.SERVER_NAME}}/api/1/organizations/organization-uri-4/"
"https://{{config.SERVER_NAME}}/api/1/organizations/organization-uri-5/"
</code></pre>

<p>{% trans %}Now we'll be able to retrieve a unique organization thanks to the returned URI:
{% endtrans %}</p>

<pre><code class="json">$ http $API'organizations/premier-ministre/' | jq '.'</code></pre>
<pre><code class="json">$ http $API'organizations/organization-uri-x/' | jq '.'</code></pre>

<p>{% trans %}That's a lot of data to compute. Let's refine these data, if we want only metrics:
{% endtrans %}</p>

<pre><code class="json">$ http $API'organizations/premier-ministre/' | jq '.metrics'</code></pre>
<pre><code class="json">$ http $API'organizations/organization-uri-x/' | jq '.metrics'</code></pre>

<pre><code class="json">
{
Expand All @@ -232,25 +224,25 @@ <h3>{% trans %}Browsing and retrieving data{% endtrans %}</h3>
<p>{% trans %}Or maybe just the name of the members of that organization:
{% endtrans %}</p>

<pre><code class="json">$ http $API'organizations/premier-ministre/' | jq '.members[].user.last_name'</code></pre>
<pre><code class="json">$ http $API'organizations/organization-uri-x/' | jq '.members[].user.last_name'</code></pre>

<pre><code class="json">
"Javelle"
"Pelletier"
"des victimes de spoliations"
"Mestre"
"BENVENUTO"
""
"Martin"
"Lee"
"Zhang"
"Wang"
"Nguyen"
"Garcia"
"Fernandes"
...
"Tales"
"Saint-Aubin "
"Biafora"
"Cottin"
"ROGER"
"des retraites (Premier ministre)"
"Modestine"
"Roullier"
"Roullier"
"Chignard"
"Gonzalez"
"Hernandez"
"Smith"
"Smirnov"
"Müller"
"Santos"
"Bernard"
</code></pre>

<p>{% trans %}It's really up-to-you to retrieve the data that matters to your project. Do not hesitate to go through the <a href="http://stedolan.github.io/jq/tutorial/">jq's tutorial</a> and <a href="http://stedolan.github.io/jq/manual/">manual</a> if you want to browse the API through the command-line in depth.
Expand All @@ -265,7 +257,7 @@ <h3>{% trans %}Modifying and deleting data{% endtrans %}</h3>
<p>{% trans %}If you try to modify a resource without an authentication token, a 401 will be returned:
{% endtrans %}</p>

<pre><code class="json">$ http PUT $API'organizations/premier-ministre/'</code></pre>
<pre><code class="json">$ http PUT $API'organizations/organization-uri-x/'</code></pre>

<pre><code class="json">
HTTP/1.1 401 UNAUTHORIZED
Expand All @@ -280,7 +272,7 @@ <h3>{% trans %}Modifying and deleting data{% endtrans %}</h3>
<p>{% trans %}You need to specify your API Key (see above) and use the <code>X-API-KEY</code> HTTP header. If you try to modify a resource that you're not in control of, a 400 will be returned instead:
{% endtrans %}</p>

<pre><code class="json">$ http PUT $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here</code></pre>
<pre><code class="json">$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here</code></pre>

<pre><code class="json">
HTTP/1.1 401 UNAUTHORIZED
Expand Down Expand Up @@ -321,20 +313,20 @@ <h3>{% trans %}Modifying and deleting data{% endtrans %}</h3>
<p>{% trans %}But it didn't change anything! This is perfectly normal, we forgot to specify the right data to send to the server.
{% endtrans %}</p>

<pre><code class="json">$ 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}'</code></pre>
<pre><code class="json">$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here name="Lorem ipsum" description="The quick brown fox jumps over the lazy dog." | jq '{name: .name, description: .description}'</code></pre>

<pre><code class="json">
{
"name": "Premier ministre fr",
"description": "Administration du Premier ministre."
"name": "Lorem ipsum",
"description": "The quick brown fox jumps over the lazy dog."
}
</code></pre>

<p>{% trans %}The resource has been modified with your new values. Finally, you can delete a resource with the appropriated HTTP verb (beware, no rollback is possible using the API at the moment):
{% endtrans %}</p>


<pre><code class="json">$ http DELETE $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here</code></pre>
<pre><code class="json">$ http DELETE $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here</code></pre>

<pre><code class="json">
HTTP/1.0 204 NO CONTENT
Expand All @@ -346,7 +338,7 @@ <h3>{% trans %}Modifying and deleting data{% endtrans %}</h3>
{% endtrans %}</p>


<pre><code class="json">$ http GET $API'organizations/premier-ministre/'</code></pre>
<pre><code class="json">$ http GET $API'organizations/organization-uri-x/'</code></pre>

<pre><code class="json">
HTTP/1.0 410 GONE
Expand Down