Here is an outline of possible content for a Medbiquitous API Architecture document. I included questions that we need to discuss or research.  I would like to discuss this outline in the Monday TSC call and hopefully get volunteers to look into some of the questions. 

 

  1. Principles and Objectives
    1. Light-weight 
    2. Easy to implement
    3. Secure
    4. Extensible (method extensibility/parameters, upward compatibility, extensible payload)
  2. Interaction
    1. REST
    2. Payload format (need to decide what is required)
      1. JSON
      2. XML
      3. Both (design of new data model must think about both. We can require providers to support content negotiation.)
    3. REST Guidelines 
    4. JSON Guidelines (what can this be based on?)
  3. Granularity
    1. Individual item response (JSON preferred?)
    2. Document fragment response (XML well defined subset of existing MedBiq standard documents)
    3. Need additional allowable value definitions like controlled vocabularies?
  4. API signatures
    1. PURLs - how to host, construct, querying vs persistence, item potency, concurrency
    2. /medbiq/api/…
  5. Transactions
  6. Attachments (do we need in V1?  How to do in JSON?)
  7. Notifications (do we need this?  Wait for use cases? What are notifications in this context?)
  8. Security
    1. HTTPS, PKI
    2. Updated single sign-on guidelines
      1. API oriented
      2. Latest standards
      3. Guidelines, not requirements
    3. Access Control, Labels (do we need for V1?  Guidelines)
    4. Audit (Guidelines, do we need for V1?)
    5. Digital Signatures
      1. Just include signature or assure no tampering and non-repudiation?
      2. How to include in JSON? Possibly - http://self-issued.info/docs/draft-jones-json-web-signature-json-serialization-01.html
    6. Privacy (deals with data that is stored or retrieved, also part of Access Control - is this needed for V1?)
  9. Extensibility
  10. Standard exceptions
    1. Do we have some that cross all APIs, like unknown id?
    2. Standard exception format 

Note on Content Negotiation: the following text is form our REST Web services design guidelines:

1.1             Determining Which Representation to Use

When a service supports more than one output format, the service may support the accept parameter or Accept http header in order to allow the client to select the format to use.

 

To determine what format the client wants for the representation, the client should do the following:

 

Clients should use the Accept header as the preferred indicator of format. The URI parameter is provided as a convenience for clients that have limited header support.

If the format is unsupported, then the REST service should return an error. If no content header is present but there is body content along with the request, then the service should use the same content type for the response. If the request contains no body and no content header, then the service should select a default. The default for MedBiquitous is XML.