Page MenuHomeSoftware Heritage

API: fix version 1 paper cuts
Closed, MigratedEdits Locked

Description

A number of minor, but annoying, inconsistencies can be observed in what version 1 of our API currently returns. This task keeps track of the need of fixing all of them.

Here is a WIP list:

  • the field "date" is sometimes a second-since-epoch floating point timestamp (example, example), and other a textual ISO 8601 timestamp (example). As a general rule, we should strive to always return the same type for the same dictionary key
  • the "revision" endpoint uses two separate lists for listing the parent commits: "parents", and "parents_url" (example). This makes it annoying to use and does not structurally guarantee well-formendess (e.g., the two lists can have different length). We should use a single list of dicts
  • the "release" and "revision" endpoints are inconsistent on how they indicate the author: revision (example) has "author" + "author_url", while "release" (example) has only "author" and no "author_url"

Event Timeline

zack updated the task description. (Show Details)

I agree all is to be fixed, my 2 cents though:

the field "date" is sometimes a second-since-epoch floating point timestamp (example, example), and other a textual ISO 8601 timestamp (example). As a general rule, we should strive to always return the same type for the same dictionary key

Yes, i believe the historical reason is for the /browse/origin view which uses timestamps (as an implementation detail).
The jquery calendar which permits to zoom on origins (which is not opened for now).

This makes it annoying to use ...

I don't know about that. Annoying to read maybe but to use?
The users can filter out what they don't want.

guarantee well-formendess (e.g., the two lists can have different length). We should use a single list of dicts

From an implementation point of view, the parents_url list is generated from the parents' list content.
So, no, the length won't ever be different.

We should use a single list of dicts

That poses a question about consistency. For now, every <entry-name>_url thing is separated from <entry-name> (see author, committer, etc...).
If we merge the parents one, shouldn't we do the same for every other entries?
Or do we only focus on parents here?

the "release" and "revision" endpoints are inconsistent on how they indicate the author: revision (example) has "author" + "author_url", while "release" (example) has only "author" and no "author_url"

Ok, it's the release's enricher part which is inconsistent.

All will be fixed!

I've just pushed rDWUI4dd525745214, to document that backward incompatible changes (as these we are discussing here are) might happen even without bumping the API version number.

zack added a project: Restricted Project.Feb 12 2017, 6:29 PM
zack moved this task from Restricted Project Column to Restricted Project Column on the Restricted Project board.Feb 12 2017, 6:39 PM
ardumont changed the task status from Open to Work in Progress.Feb 21 2017, 11:44 AM
ardumont updated the task description. (Show Details)

@ardumont: is anything missing before we can close this?

No, it's good for me.

But i was thinking that you may have had other stuff that you did not yet
find time to report.

zack claimed this task.