Add Postman API information to https://www.grampsweb.org/dev-backend/queries/

Gramps Web
1

I would like to contribute some information to the dev-backend Documentation for testing the API using Postman:

  1. Get the access token: make a POST type request to https://yourgramps.com/api/token/ (seems like the last forward slash is required here, omitting it will result in a Method not allowed response) with Body → raw (make sure JSON is set in the dropdown on the right):

    {
    "username": "your_username",
    "password": "your_password"
}

    Click on Send.
    Copy the value of the access_token property from the response.

  2. Make an API request using the access token: Prepare a GET type request to https://yourgramps.com/api/metadata (seems to work with or without the last forward slash?), set Authorization → Auth Type = Bearer token and paste the Access token you copied from the previous step in the Token field. Body can be reset to none.
    Click on Send. You should get a response with the metadata from your Gramps Web API.

  3. You should be able to follow the same method in step 2 for the following endpoints (as documented at Swagger UI):

    • /api/people
    • /api/families
    • /api/events
    • /api/places
    • /api/citations
    • /api/sources
    • /api/repositories
    • /api/media
    • /api/notes
    • /api/tags
    • /api/transactions/history
    • /api/types
    • /api/name-formats
    • /api/name-groups
    • /api/bookmarks
    • /api/filters
    • /api/translations
    • /api/timelines/people
    • /api/reports
    • /api/facts
    • /api/holidays
    • /api/exporters
    • /api/users
    • /api/importers
    • /api/trees

    From my tests it seems that /api/config does not work, I get the following response:

    <!doctype html>
<html lang=en>
<title>403 Forbidden</title>
<h1>Forbidden</h1>
<p>You don&#39;t have the permission to access the requested resource. It is either read-protected or not readable by
 the server.</p>
1 Like
2

For some reason my configuration was empty. I have a heck of a time setting the configuration when docker compose up -d ing Gramps Web. I have tried with environment variables but they don’t seem to get picked up.

After another restart of the container I started getting an empty response {} from the /api/config endpoint, but at least it was now there.

I finally succeeded in setting values for the configuration sending PUT requests (POST did not work) like so:

  • PUT /api/config/EMAIL_HOST, using Authentication → Bearer token set to the Access token value, Body → raw (JSON) with:
    {
  "value": "smtp.gmail.com"
}

and repeating this for every value I wanted to set.
Now when I issue a GET request to /api/config I finally see all of the configuration values. I restarted the Gramps Web container for good measure, but alas email notifications are still not working arghh.

3

Good idea, if you want to submit a Postman version of https://gramps-project.github.io/web/dev-backend/queries/ to GitHub - gramps-project/gramps-web-docs: Documentation for Gramps Web, that would be great.

You can also have a look at GitHub - DavidMStraub/gramps-web-api-client: A simple Python client to interact with a Gramps Web API instance - I wrote that to do manual API queries in Python without having to worry about tokens all the time.

4

Ok I submitted a PR with information on using Postman. Postman also allows you to store the access token for future requests. Once it’s all setup it is quite nice to use the graphical interface, not only for localhost but even for a production instace. It allows setting Vault secrets so passwords aren’t ever shared with the cloud.