Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  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 -
    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:

  • Look for an accept URI parameter. This parameter's value should follow the same format as the Accept header
  • Else, look for the Accept http header


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.