search

osuosl / timesync

A time tracking API
2 stars 1 forks source link

POST projects slug needs clarification #79

Closed mathuin closed 7 years ago

mathuin commented 8 years ago

https://timesync.readthedocs.io/en/latest/api.html#post-projects-slug

The following text is included as a note block:

If a slugs field is passed to /projects/:slug, it is assumed to overwrite the existing slugs for the object. Any slugs which already exist on the object but are not in the request are dropped, and the slugs field on the request becomes canonical. (Assuming all of the slugs do not already belong to another project.)

I thought I understood, until I got to the parenthetical portion of the text. This needs examples or some additional clarification. If a project has slugs ["a", "b"], and a slugs field of ["b"] is POSTed to that project, the "a" slug is dropped. If a slugs field of ["c", "d"] is POSTed to that project and no other project has those slugs, then both "a" and "b" are dropped, and "c" and "d" are the only slugs for this project. If a slugs field of ["c", "d"] is POSTed to that project but another project has "c" as a slug, what happens? What if one project has "c" and another project has "d"? What if the user POSTing does not have sufficient privilege to see one or more of the projects holding those other slugs?

MorganEPatch commented 8 years ago

To clarify right now and for whoever fixes these docs, the answer is that if any of the slugs provided belong to any other projects (regardless whether they're the same or different projects, and regardless of permissions), a Slug Already Exists error is returned containing the list of slugs already associate with a project. Otherwise, the project's slugs are set to precisely the list provided.

mathuin commented 8 years ago

Your response does not address what happens to the project if not all slugs being POSTed currently exist. Since the presence of at least one existing slug causes an error to return, are the other non-existing slugs successfully set? How does the client know that some parts succeeded and some parts failed?

MorganEPatch commented 8 years ago

In the event that any error occurs during a POST or DELETE operation, an error is returned to the client, and the operation is terminated. As is consistent with the behavior of all of the rest of the API, if at least one slug already belongs to another project, a Slug Already Exists error is returned, and the project is not modified.