Design Organizations API

[oliverroick]

• List (sortable, filter, search)
• Create
• Get Detail
• Update
• Archive/Unarchive
• Delete(?)

[ian-ross]

Yeah, I wondered about delete too...

[oliverroick]

@Cadasta/cadasta-dev: I started a document outlining the API for organisations

Some issues to discuss:

• We should implement API versions early on. I don't expect us to introduce any breaking API changes in the near future, but we should have basic versioning in place. For I suggest to add v1 to API URLs (https://api.cadasta.org/v1/...). DRF supports versioning.
• Should we allow identifying entities via ID or slug field only? (/organizations/org-name/ vs. /organizations/8sahd43saxh7/)
• We need a concept of an archived entity.
  • Who can archive and unarchive an entity?
  • Who can access archived entities?
• An entity can be archived by updating the archived attribute to true, via PATCH. Any other thoughts?
• Deleting entities (as in purging them from the data base); is it required now?
• Structuring contacts: @ian-ross suggested to use hcard format. There's h-card, a draft to update the original spec. I’m not sure how closely we should follow the spec and if we should fully implement it. Some things in there are a bit overhaed.
• Validation errors that return HTTP 400: I suggest to follow DRF built in exception handling.

[ian-ross]

• API versions Agreed, and agreed on api.cadasta.org/v1/... instead of any funny business with media types.
• Entity identification Organisations and projects should be identified by name, perhaps users too, all others by "random ID"/slug.
• Archiving Q: Who can archive and unarchive an entity? A: Whoever has the blah.archive permission can archive, whoever has blah.unarchive can unarchive, as well as the user who originally archived the entity. Q: Who can access archived entities? A: Anyone who has the blah.view-archived permission!
• Archiving via PATCH Not sure about this: it feels like it ought to be a "heavier" operation than a PATCH to a single binary flag. But that's really what it is, so it's the logical way to do it.
• Deleting entities Deletion (total purge) should only apply to previously archived organisations and projects. It's something to implement later, I think, since we also want to make it possible to export project data before purging. Deletion of "normal" objects (parties, parcels, etc.) will be managed by the versioning system (once it's written) so you'll be able to do straightforward DELETE on resources and they'll be deleted from view, but still there for those who know to look for them.
• Structuring contacts I don't have any particular feeling one way or another - I suggested hCard because it's a pre-existing standard and it means less thinking for us!
• Validation errors Agreed!

[wonderchook]

• API versions: agreed
• Entity identification: yes for identifying by name for organizations, projects. I think users makes sense as well
• Archiving: yes who has the permission. I would say the Org admin or a Super Admin
• Deleting: let's do that later. And yes you should have to archive first
• Structuring contacts: hCard makes sense