JSON format
If you access the API through the website, you will receive data in HTML format. This format is not particularly useful if you want to develop an end-to-end workflow. For this reason, the flatfile endpoint can also return data in JSON format if you request it through any program capable of submitting HTTP requests (e.g., Python, cURL). The API is stateless, which means that user information is not stored as a session variable, as it is in the webpage. We use authorization tokens to make sure that users are who they claim to be, and that they are authorized to retrieve the requested information. This means that making a JSON API request requires an authentication step to generate a token, followed by a data request that transmits the token along with the information request.
Authentication / Authorization
To retrieve an authorization token, you must first authenticate using HTTP Basic Authentication.
This is a method in which your username and password are transferred to the server as headers,
and the server then checks the credentials in a similar manner to form-based authentication. When
you submit an authentication request, information is returned in a JSON array format with the
following fields:
{'token' : 'yourtoken', 'message' : 'Welcome username!', 'success' : true }
You will need to parse the JSON string into an array in order to extract the token.
When you submit your authentication request, you should include the following headers:
{'User-Agent': 'XY', 'Accept' : 'application/json'}
The User-Agent value identifies the client to the server. The server requires a User-Agent field
to be present. The 'Accept' header is required by the server to retrieve data through an HTTP api
request.
Submitting a request
Once you have authenticated and retrieved your token, you can then submit a GET request. The token
should is included in the header information as follows:
{"User-Agent":"XY", "Accept":"application/json","Authorization": "Bearer.token"}
where "token" is replaced by the token you retrieved when you authenticated. The token expires
after 2 hours.
Python scripts
We have prepared a Python class and associated Jupyter notebook for handling authentication
and GET queries through the API. You can download these files here:
gmdb_api.py
api_example.ipynb
We use ipywidgets to create username and password fields in the Jupyter notebook. It's tempting
to store your username and password in plain text within a script because that would be very
convenient. However, we suggest that you resist the temptation to do so. It is too
easy to forget that you have sensitive information stored in the script, and you might accidentally
share it with someone else. You can store this information in many different ways, and the
Python class and Jupyter notebook above are just one example you might utilize.