the first version of the Gramps Web API has been released today.
What is it?
It is a new Python package that allows yout to host your family tree database on a web server and access it via a HTTP REST API. Currently, only read access is implemented, but adding write access (to add new or modify existing objects like people, events, media, …) is on the roadmap.
Why is this useful?
The main use case is arguably to serve as a backend for connected apps (web or mobile) as alternative ways to access a Gramps family tree - either to share your work with others, or when you’re on the go without a laptop. I am working on a web frontend called Gramps.js (which I plan to talk about in another post), which is one possible application. But having a standard backend enables the community to build many different tools on the same powerful framework. A discussion that triggered the development of the package can be found here.
What does it look like?
On the Github project page, you can find a link to the API documentation and a demo server.
What is the status of the project?
The first version of the package was released to PyPI today, but most of the work for this release was done a couple of months ago. Read access is already quite complete, while write access has not been implemented yet. So far, only three people have contributed to the code base, so it would be great to have more people contributing.
How can I use it?
Please see the documentation on Github.
As a matter of policy, can we open a conversation about the defaults for private data?
It seems defaults should always favor privacy, even above being exhaustively inclusive. That programmers should have to explicitly request PRIVATE data rather than the converse.
Also, I realize this is a filter which innately makes it an EXCLUDE. But to avoid the ambiguities of double negatives, could privacy settings be in terms of INCLUDE rather than EXCLUDE?
In principle I agree of course about the importance of privacy. But I think in this specific case it’s not an issue.
In general, the API should never be used without authentication (i.e. completely exposed to the public), unless it’s for local testing. This is stressed in the documentation of the DISABLE_AUTH parameter (that exists for purposes of local testing).
Now, for an authenticated user, whether they are able to see private records or not, in any API call, depends on their authorization level. [As I’m writing this, I realized we haven’t documented these authorization levels. Oops! Issue added.] For instance, if you view /people/ and you do have ViewPrivate permissions, you’re going to see all people, include private ones. If you don’t have that permission, you’re only going to see non-private people.
The purpose of the private parameter in the exporters endpoint you mentioned is just relevant for a user who does have ViewPrivate permissions but wants to generate a DB export without private records - for instance to send it to another researcher. Changing the default to True here wouldn’t have a security benefit. In practice, I would assume that any application using this endpoint to generate a DB export will offer the user a checkbox “exclude private records”, as Gramps desktop is doing, and will set the private query parameter accordingly.
Regarding the authorization levels, I’ll wait for the documentation, but I’m hoping there will be a way to define authorization groups using person filters.
Currently when we share our trees, whether by exporting to GEDCOM or generating a narrative web site, we’re able to use a person filter to limit the results. In other words, we create a person filter for a subset of the population, and distribute the results only to members of that subset.
I imagine that could be accomplished by associating each web user id with one or more authorization groups, each of which is associated with a person filter. That would be sufficient for broad groups with many members (for example, the Smith vs. Jones sides of the family tree.)
For more fine-grained use cases, such as letting a user view only their “relatives”, it could require associating each web user id with a particular Gramps person handle. In other words, the administrator would create a person filter that defines the scope of “relatives” given a starting person, and the user’s person handle would be input to the filter. This feature need not preclude a web user who is not represented by a person in the tree from belonging to some other authorization group.
In any case, such filtering should interoperate with any standard authorization groups based on “private” or “living” persons.
Another question would be whether the backend could support third-party authentication systems, such as Google. Obviously that would just be for authentication, not authorization.
Yes, what you describe would be perfect! For my own tree, I am currently setting all objects associated to living people as private and do not share them, which has the unfortunate side effect that my cousins etc. don’t even see their own data. We started with private/non-private because that’s the easiest to implement (just a binary setting).
One issue with person-filter-based permissions is that this is only really well defined for people objects. For all other object types, it’s tricky whether they should be viewable by the person or not, and in particular it’s probably not possible with the current filter proxy DB classes in Gramps. Just one example: if I’m witness (not primary participant) at a marriage, should I be allowed to see all media related to the event? The photos, the marriage certificate? So, tricky problems, but we should find a way.
Concerning external authentication: that should not bee too difficult to implement I believe.