client/person CRUD methods

[Eric Jahn]

Just to get the discussion rolling, here are some proposed Create/Read/Update/Delete methods for a person/client's record.  What do you think?  -Eric

===client/add===

Adds a new client to the system.  Should perform matching/unduplication.

====method input:====
(requires basic authentication)

application/xml. HTTP POST hmis:Person type instance from the schema at:
http://www.hmis.info/schema/3_0/HUD_HMIS.xsd

====method return:====
text/plain.  The newly sequentially generated integer client id in the OpenHMIS.  If the method is unsuccessful, a "-1" is returned, with any XML Parsing errors in the message.

documentation for hmis:Person:
http://www.hmis.info/schema/3_0/docs/HUD_HMIS.xsd0.html

check for XML validity.
----

===client/get===

Retrieves a client record by ID.  This example url will retrieve the client with an id of ‘4’
http://domain.com/client/get?id=4

====method input:====
(requires basic authentication)

an HTTP GET url integer ID parameter.

====method return:====
application/xml.  An hmis:Person XML instance. 

If a client ID that does not exist or is not accessible is requested, the method responds with
with a "-1" return value.
----

===client/update===

Updates an existing client in the system.  The url parameter targets the to-be-updated client recorded.  The POSTed XML provides the updated client record information. 

====Example:====
http://domain.com/client/update (with HTTP POST XML attached to the request)

====method input:====
(requires basic authentication)

application/xml. HTTP POST hmis:Person type instance from the schema at:
http://www.hmis.info/schema/3_0/HUD_HMIS.xsd

====method return:====
text/plain.  Returns the updated client id in the OpenHMIS.  If the method is unsuccessful, a "-1" is returned.

====documentation for hmis:Person:====
http://www.hmis.info/schema/3_0/docs/HUD_HMIS.xsd0.html

check for XML validity. 
----

===client/delete===

This web method actually simply inactivates the record, if it wasn’t already inactive. 

====Example:====
http://domain/client/delete?id=5

====method input:====
(requires basic authentication)

HTTP GET url integer “id” parameter.

====method return:====
Returns "200" if successful and “-1” if it failed to inactivate the client (if no matching record found, or insufficient permissions, etc.).
----

[Darin Patterson]

Hey Eric,

I'm glad you've got the ball rolling here.  

The interesting thing about what I think would be typical uses of this API is that I would imagine the system making the API call wouldn't know whether it should complete an "add" or "update"; because it is unaware of whether the client already exists in the target database.  Essentially, I would imagine that duplication determination would be up to the system hosting the API; not the one calling the API.  As such, it would seem that the Client/Add method would return 2 indicators: 

1. Indication of whether a new client record was created or did the record already exists?

2. The ID of the existing client or newly created client

What do you think?

[Eric Jahn]

Darin,
This API behavior for client submission makes sense to me.  The only scenario I could see this being a problem would be where the target system is a really simple data warehouse that doesn't possess an unduplication algorithm at its disposal.  It sort of gets into the definition of this API's purpose: is it an API for sending HMIS data, or an API for sending data between HMIS systems?  I would answer, "yes, both".  How about this (please forgive the car analogy): we provide an "automatic transmission" client/submit API call that assumes unduplication logic in the target system, and also a more "manual" set of calls (client/add, client/update) that lets the client system state their intentions more directly?  Of course, if a client uses manual API methods, that wouldn't keep a system actually possessing unduplication logic from handling the requests with its unduplication logic, and the client wouldn't know any better.  And the client wouldn't necessarily need to know any better; if the client does need to know more information, then it should use the automatic method to get the more detailed response information you suggested).  Would this work?

Which brings to mind: we should post these method calls we are working on into a publicly shared doc or something.  -Eric Jahn

[Eric Jahn]

I wonder if we can't borrow anything from CardDAV, swapping out the payload for something else (HMIS XML or NIEM HS).

http://www.rfc-editor.org/rfc/rfc6352.txt

This would add the functionality of synchronization of client record sets also.

Eric Jahn
Data Architect
Alexandria Consulting LLC
St. Petersburg, Florida
727.537.9474

--
You received this message because you are subscribed to the Google Groups "hmis-api" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hmis-api+u...@googlegroups.com.
To post to this group, send email to hmis...@googlegroups.com.
Visit this group at http://groups.google.com/group/hmis-api.
To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/01a10ff4-8d87-4ef1-baca-a238c295c89c%40googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.