search

openreferral / api-specification

This is the working repository for Open Referral's Human Services Data API protocols.
https://openreferral.readthedocs.io/en/latest/hsda/
Other
29 stars 13 forks source link

Verbs #26

Open kinlane opened 7 years ago

kinlane commented 7 years ago

The major part of this release was ensuring there was POST, PUT, and DELETE methods for the entire surface area of the HSDS schema.

right now we use POST for adding, and PUT for updating. Both use the body and PUT updates the entire resource (ie. organization, location, service, contact). I suggest we add PATCH, allowing for partial updates, as well as OPTIONs further defining the surface area.

switzersc commented 7 years ago

Do you think having both POST and PUT is necessary? My thinking is that if each resource has to have a unique external identifier provided on creation (maybe a tax code or some other public identifier, in the same vein as a Master Person Index), then a PUT works as an idempotent create, and then you don't have to make clients choose which to use and create actions are always safe. However, this assumes the existence of a unique identifier provided by the client on create, which we may not have...

+1 to PATCH

switzersc commented 7 years ago

Ah, I realize that my comment really only applies to things that can have an external identifier, like an organization with a tax ID, and then if only those resources allowed PUT on create instead of utilizing a POST, that might feel weird/inconsistent... But I do wonder about allowing PUT to create for some resources while still having a POST? I just think this is nice from a client perspective.

kinlane commented 7 years ago

Good question. You know..I'm going to wait for consumers to weigh in. It feels dangerous to me like I am imposing my views on the design too much. I'm going to leave as is, and wait for more community / vendor feedback.

NeilMcKLogic commented 6 years ago

If I don't see an existing thread on a related topic, I'll add it later today: How does one do a full-record Insert, Update and/or Delete (say, an Organization and all related/child records) without having to call the endpoint for each record type?