{"type":"doc","content":[{"type":"paragraph","content":[{"text":"This is the technical API documentation (focusing on client devs) for the ","type":"text"},{"text":"REST Module","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469882"}}]},{"text":". For general REST web service information and user documentation, see the ","type":"text"},{"text":"module page","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469882"}}]},{"text":".","type":"text"}]},{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"a0e08b1a-9840-4c92-a5ce-ca5b88efe010"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources","type":"text"}]},{"type":"paragraph","content":[{"text":"Every available object in the web services (ws) module is written up as a resource. The resource class defines the properties that are exposed and the setters that are available. The class also defines the representations and what goes in them (ref vs default vs full, see below for more on representations).","type":"text"}]},{"type":"paragraph","content":[{"text":"See documentation about resources and their URIs here: ","type":"text"},{"text":"REST Web Service Resources in OpenMRS 1.9","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25475990"}}]}]},{"type":"paragraph","content":[{"text":"You can also see some generated URI documentation on the \"Help\" page that the module puts into its Administration page section.","type":"text"}]},{"type":"paragraph","content":[{"text":"There is a uri that lists off the currently available resources in the installation (including module-provided resources):","type":"text"}]},{"type":"codeBlock","content":[{"text":"/module/webservices/rest/apiDocs.htm\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Subresources","type":"text"}]},{"type":"paragraph","content":[{"text":"There are some objects that are not defined or do not make sense apart from their parent object. These we refer to as subresources. Examples are PersonNames, PersonAddresses, ConceptNames, etc. You can act on subresources under the parent url.","type":"text"},{"type":"hardBreak"},{"text":"Examples:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Editing a person's name","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"POST /openmrs/ws/rest/v1/person/:target_person_uuid/name\n{\n\t\"givenName\": \"John\",\n\t\"familyName\": \"Smith\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"A subresource can have only one parent. If it seems like an object has two or more parents, then it is most likely a top-level resource. E.g. \"encounters\" should not be a subresource of \"patient\" and \"location\" (answering questions of both \"all encounters of a patient\" and \"all encounters at a location\"). Instead, these should be queries on the encounter resource: /ws/rest/v1/encounter?patient=349234-2349234 and /ws/rest/v1/encounter?location=3423482-34923-23","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources with Subtypes","type":"text"}]},{"type":"paragraph","content":[{"text":"Some resources can have multiple subtypes, for example the ","type":"text"},{"text":"order","type":"text","marks":[{"type":"code"}]},{"text":" resource contains ","type":"text"},{"text":"drugorder","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"testorder","type":"text","marks":[{"type":"code"}]},{"text":" subtypes. When creating a resource that has subtypes via a POST, you must specify which subtype of the resource you are creating, with a special ","type":"text"},{"text":"t","type":"text","marks":[{"type":"code"}]},{"text":" property of the object. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"POST /openmrs/ws/rest/v1/order\nBody content:\n{\"t\": \"testorder\", /*... and other properties */}","type":"text"}]},{"type":"paragraph","content":[{"text":"If you GET a resource that has subtypes, each result will be of one of those subtypes, which you can see by looking at the special ","type":"text"},{"text":"t","type":"text","marks":[{"type":"code"}]},{"text":" property of each result. You may query for only a certain subtype of a resource by providing a ","type":"text"},{"text":"t","type":"text","marks":[{"type":"code"}]},{"text":" query parameter, like ","type":"text"},{"text":"GET /ws/rest/v1/order?t=drugorder&otherparams=values","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"URI Conventions","type":"text"}]},{"type":"paragraph","content":[{"text":"Because there are so many options when creating REST urls, we have laid out a set of conventions that all REST developers should follow. This will keep our web service api looking neat and uniform across all different types of objects and modules.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"resource","type":"text","marks":[{"type":"em"}]},{"text":",","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET /ws/rest/v1/","type":"text"},{"text":"resource","type":"text","marks":[{"type":"em"}]},{"text":"?q=","type":"text"},{"text":"query","type":"text","marks":[{"type":"em"}]},{"text":" = search","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GET /ws/rest/v1/","type":"text"},{"text":"resource","type":"text","marks":[{"type":"em"}]},{"text":"/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":" = retrieve","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"POST /ws/rest/v1/","type":"text"},{"text":"resource","type":"text","marks":[{"type":"em"}]},{"text":" = create","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Request body contains data to persist (not in request params)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"POST /ws/rest/v1/","type":"text"},{"text":"resource","type":"text","marks":[{"type":"em"}]},{"text":"/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":" = partial update of the resource","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Request body contains just the fields to update (not in request params)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PUT = replace value of entire object","type":"text"},{"text":" (we don't use this yet)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"DELETE /ws/rest/v1/","type":"text"},{"text":"resource","type":"text","marks":[{"type":"em"}]},{"text":"/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":" = void for data, retire for metadata","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"DELETE /ws/rest/v1/","type":"text"},{"text":"resource","type":"text","marks":[{"type":"em"}]},{"text":"/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":"?purge=true = purge (aka delete from the database entirely)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not put verbs in the URL; represent them with sub-resources.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For example, instead of addNameToPerson, we POST to /ws/rest/person/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":"/names","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"URLS:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Are prefixed with /ws/rest/ due to servlet forwarding in OpenMRS, followed by an API version number (currently /v1)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The URL should be written in all-lowercase ASCII letters","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No special characters (e.g. no spaces or underscores)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Hyphens are ok if absolutely necessary","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No extensions allowed (acceptHeader will be used to specify json or xml content. All json for release 1.0)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Subresources should have their URIs inside the URI of their parent (like /ws/rest/person/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":"/name/","type":"text"},{"text":"nameuuid)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Domain objects that are separately managed get their own URI. (e.g. /ws/rest/v1/enrollment/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":" instead of /ws/rest/v1/program/","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"em"}]},{"text":"/enrollments/","type":"text"},{"text":"uuid)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Hide (don't expose) \"helper\" classes as much as possible (e.g. web service clients should never see ConceptSet, etc)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Resource names should usually be the same as the domain objects they represent, but they may differ if the domain object name is confusing.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For example org.openmrs.PatientProgram is /ws/rest/v1/enrollment","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"E.g: When saving or editing a property on a \"Concept\" object, the conceptDatatype property can be simply the uuid. In addition, for most metadata, the \"name\" is unique across all active metadata, so that can also be used in place of the uuid when saving as well (POST or PUT).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Sample REST calls","type":"text"}]},{"type":"paragraph","content":[{"text":"If you are looking for some sample REST calls, please see ","type":"text"},{"text":"Sample REST calls","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25494138"}}]},{"text":". You can also explore controller tests to see which requests are possible: ","type":"text"},{"text":"https://github.com/openmrs/openmrs-module-webservices.rest/search?q=Controller+test&type=Code","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-module-webservices.rest/search?q=Controller+test&type=Code"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Limiting the number of results and paging","type":"text"}]},{"type":"paragraph","content":[{"text":"When you do a GET request that returns a very large number of results (either by getting all instances or doing a search), the number of results returned is limited.","type":"text"}]},{"type":"paragraph","content":[{"text":"Clients may request more or fewer results with the ","type":"text"},{"text":"limit","type":"text","marks":[{"type":"em"}]},{"text":" parameter. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl -u admin:test -i 'http://localhost:8080/openmrs/ws/rest/v1/concept?limit=2'\n","type":"text"}]},{"type":"paragraph","content":[{"text":"The above will return only 2 concepts. To retrieve the next page of two concepts, use the ","type":"text"},{"text":"startIndex","type":"text","marks":[{"type":"em"}]},{"text":" tag. For example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl -i 'https://localhost:8443/openmrs/ws/rest/v1/concept?limit=2&startIndex=2'\n","type":"text"}]},{"type":"paragraph","content":[{"text":"As a system administrator you can configure both the default limit (applied whenever the client does not specify a limit) and the absolute limit (which the client is not allowed to exceed), from the \"Settings\" page of the ws module.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Including Retired metadata and Voided/Deleted data","type":"text"}]},{"type":"paragraph","content":[{"text":"A normal REST query will not include Retired metadata or Deleted/Voided data. You may send an ","type":"text"},{"text":"includeAll=true","type":"text","marks":[{"type":"code"}]},{"text":" query parameter to include retired/deleted data.","type":"text"}]},{"type":"paragraph","content":[{"text":"Both the REST and Java API follow the same default behaviour except for the case of getting metadata from the Java API, see the summary table below:","type":"text"}]},{"type":"table","content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"REST API","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Java API","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"GET dataresource","type":"text","marks":[{"type":"code"}]},{"text":" → ","type":"text"},{"text":"excludes","type":"text","marks":[{"type":"strong"}]},{"text":" voided by default","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"getAll[Data]","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"→","type":"text"},{"text":" ","type":"text"},{"text":"excludes","type":"text","marks":[{"type":"strong"}]},{"text":" voided by default","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"GET metadataresource","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"→","type":"text"},{"text":" ","type":"text"},{"text":"excludes","type":"text","marks":[{"type":"strong"}]},{"text":" retired by default","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffe7e7","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"getAll[Metadata]","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"→","type":"text"},{"text":" ","type":"text"},{"text":"includes","type":"text","marks":[{"type":"em"}]},{"text":" retired by default","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Date/Time with Time Zones","type":"text"}]},{"type":"paragraph","content":[{"text":"It is strongly recommended to always submit the full date + time + timezone in any REST POST query.","type":"text"}]},{"type":"paragraph","content":[{"text":"The format of the date/time should be: ","type":"text"}]},{"type":"paragraph","content":[{"text":"“","type":"text"},{"text":"2016-12-25T19:02:34.232+0700","type":"text","marks":[{"type":"strong"}]},{"text":"”","type":"text"}]},{"type":"paragraph","content":[{"text":"(the milliseconds are optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"e.g.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Creating an obs","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"POST /ws/rest/v1/obs\nBody content:\n{\"obsDatetime\": \"2016-12-25T19:02:34.232+0700\", /*... and other properties */}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"If no time zone is provided or it is not formatted correctly, the service will suppose that the date and time are provided at local time (server time). This can have deep repercussions, so make sure to always send a valid time zone.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Response Format","type":"text"}]},{"type":"paragraph","content":[{"text":"Spring allows us to offer both json and xml formats for every object. If you want to receive a json response, be sure to insert a header of \"Accept: application/json\". If xml is your thing, use \"Accept: application/xml\".","type":"text"}]},{"type":"paragraph","content":[{"text":"When POSTing content, use the \"Content-Type\" header to specify the data format you are sending to the server.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Browsers have their Accept header fixed at: Accept: text/html,application/xhtml+xml,application/xml;. Therefore you will always see xml returned in a browser.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Representations","type":"text"}]},{"type":"paragraph","content":[{"text":"The objects returned by web service calls are variable in their properties. In general there are three different representations that exist: ref, default, full. It is possible for modules to provide more representations for their objects. (TODO: document what method to call to get the available reps)","type":"text"}]},{"type":"paragraph","content":[{"text":"To change between representations, use the \"v\" query parameter: ","type":"text"},{"text":"...?v=ref","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"...?v=full","type":"text","marks":[{"type":"code"}]},{"text":". Using ","type":"text"},{"text":"...?v=default","type":"text","marks":[{"type":"code"}]},{"text":" is invalid. Simply leave that parameter off.","type":"text"}]},{"type":"paragraph","content":[{"text":"Web service calls that return lists of objects will put those objects into the \"ref\" representation.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Ref","type":"text"}]},{"type":"paragraph","content":[{"text":"When an object is a child resource on another object (e.g. conceptDatatype property on Concept object), the full ConceptDatatype object is not returned by default. Instead, a \"ref\" kind of class with String properties for ","type":"text"},{"text":"uuid","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"links","type":"text","marks":[{"type":"code"}]},{"text":", and a ","type":"text"},{"text":"display","type":"text","marks":[{"type":"code"}]},{"text":" fills the concept.conceptDatatype property. The ref looks like this:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Ref example","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"concept.conceptDatatype \\->\n{\ndisplay: \"Numeric\",\nuuid: \"8d4a4488-c2cc-11de-8d13-0010c6dffd0f\",\nlinks: {\n self: \"http:/../openmrs/ws/rest/v1/conceptdatatype/8d4a4488-c2cc-11de-8d13-0010c6dffd0f\"\n }\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Custom Representations","type":"text"}]},{"type":"paragraph","content":[{"text":"(Note: requires version 1.1 of the module)","type":"text"}]},{"type":"paragraph","content":[{"text":"You can set the \"v\" parameter to a string that explicitly states all of the reps for the class and children classes:","type":"text"},{"type":"hardBreak"},{"text":"e.g.","type":"text"}]},{"type":"codeBlock","content":[{"text":"v=custom:(uuid,datatype:(uuid,name),conceptClass,names:ref)\n","type":"text"}]},{"type":"paragraph","content":[{"text":"fuller explanation:","type":"text"},{"type":"hardBreak"},{"text":"the main resource will return:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"uuid property","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"conceptClass property as default rep","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"names as ref rep","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"datatype will have custom rep:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"uuid property","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"name property","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"To fetch the full ConceptDatatype data, a second call to the links.self uri: ","type":"text"},{"text":"http:/../openmrs/ws/rest/v1/conceptdatatype/8d4a4488-c2cc-11de-8d13-0010c6dffd0f","type":"text","marks":[{"type":"code"}]},{"text":" is needed.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Default","type":"text"}]},{"type":"paragraph","content":[{"text":"This representation is returned for objects when there is no \"v=\" parameter given. Most properties will be included and \"refs\" of some subobjects will also be listed.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Full","type":"text"}]},{"type":"paragraph","content":[{"text":"The full representation is meant to be used when subsequent calls are not desired or some uncommonly needed properties (like audit info) are needed.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authentication","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Nearly every method (other than the /session endpoint) in the OpenMRS API requires authentication; therefore, every method in the webservices module needs to have an authenticated user in order to work.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There is a filter defined on the module that intercepts ","type":"text"},{"text":"all calls","type":"text","marks":[{"type":"em"}]},{"text":" and authenticates the given request. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Currently, only BASIC authentication is supported. Along with the HTTP request, a request header of ","type":"text"},{"text":"Authorization: Basic (base64 of username:password)","type":"text","marks":[{"type":"strong"}]},{"text":" needs to be sent.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Alternatively, a session token can be used. ","type":"text"},{"text":"GET /openmrs/ws/rest/v1/session","type":"text","marks":[{"type":"strong"}]},{"text":" with the BASIC credentials will return the current token value. This token should be passed with all subsequent calls as a ","type":"text"},{"text":"cookie named jsessionid=","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b79d52ce-c4f1-4844-8f14-66581ececdd8"}}]},{"text":"token","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b79d52ce-c4f1-4844-8f14-66581ececdd8"}},{"type":"em"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A DELETE call on the /openmrs/ws/rest/v1/session will logout the user and end the session.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Getting all location without authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"Fetching locations requires you to authenticate the user first. If it is a required to display all locations prior to login or without authentication you can do it by using ","type":"text"},{"text":"GET .../openmrs/ws/rest/v1/location?tag=Login%20Location","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Changing your password","type":"text"}]},{"type":"paragraph","content":[{"text":"Since version 2.17 of the webservices.rest module:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"After authenticating you can change your own password, by ","type":"text"},{"text":"POST .../openmrs/ws/rest/v1/password","type":"text","marks":[{"type":"strong"}]},{"text":" with ","type":"text"},{"text":"oldPassword","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"newPassword","type":"text","marks":[{"type":"strong"}]},{"text":" in the request body.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An administrator (with the ","type":"text"},{"text":"EDIT_USER_PASSWORDS","type":"text","marks":[{"type":"strong"}]},{"text":" privilege) can change the password for other users by ","type":"text"},{"text":"POST ...","type":"text","marks":[{"type":"strong"}]},{"text":"/openmrs/ws/rest/v1/password/","type":"text","marks":[{"type":"strong"}]},{"text":" with ","type":"text"},{"text":"newPassword","type":"text","marks":[{"type":"strong"}]},{"text":" in the request body.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Links","type":"text"}]},{"type":"paragraph","content":[{"text":"A resource can have any number of \"links\" in the links attribute. Generally, these will be links to other representations (see above), but they also could be to other types of relationships between objects: things like \"parent\", etc.","type":"text"}]},{"type":"paragraph","content":[{"text":"A \"ref\" representation will contain a link to \"self\" that is the default rep. A \"default\" rep will have a link to \"full\" that is the same object except with all properties included.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Audit Info","type":"text"}]},{"type":"paragraph","content":[{"text":"The full representation of object contains a property called auditInfo. You can find the creator, changer, and voider/retirer information here.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"auditInfo","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"creator\ndateCreated\nchangedBy\ndateChanged\n","type":"text"}]},{"type":"paragraph","content":[{"text":"If the object is data and so is voidable, you will additionally see:","type":"text"},{"type":"hardBreak"},{"text":"voidedBy","type":"text"},{"type":"hardBreak"},{"text":"dateVoided","type":"text"},{"type":"hardBreak"},{"text":"voidReason","type":"text"}]},{"type":"paragraph","content":[{"text":"If the object is metadata and so is retirable, you will see:","type":"text"},{"type":"hardBreak"},{"text":"retiredBy","type":"text"},{"type":"hardBreak"},{"text":"dateRetired","type":"text"},{"type":"hardBreak"},{"text":"retireReason","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"retired\" and \"voided\" boolean properties are on the ref/default/full representations. The ref rep will only contain the property if the object if isVoided/isRetired returns true.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Versioning","type":"text"}]},{"type":"paragraph","content":[{"text":"The OpenMRS API will change over time and this will necessitate the rest representations and urls to be modified as well. The first release of the module will be version \"v1\". The entire rest api is versioned with this same number:","type":"text"}]},{"type":"paragraph","content":[{"text":"/ws/rest/v1/patient/2342-34-DDD-23-2ADF","type":"text"},{"type":"hardBreak"},{"text":"/ws/rest/v1/concept/AFD21-239D3-5233234","type":"text"},{"type":"hardBreak"},{"text":"etc","type":"text"}]},{"type":"paragraph","content":[{"text":"If/when (hopefully never) we make a major change to the entire rest setup, we will change this to v2. (e.g. ","type":"text"},{"text":"change from json to kson","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"0a175499-2133-471c-a265-9435d7d2fbe2"}}]},{"text":")","type":"text"}]},{"type":"paragraph","content":[{"text":"Each resource can also refer to different underlying api object versions. Each object declares a resourceVersion property that specifies which version of the API it is required to work in. This works similar to an @since annotation.","type":"text"}]},{"type":"paragraph","content":[{"text":"The actual visible version of the '''module''' will be incremented independenty from openmrs AND from the version of the rest api.","type":"text"}]},{"type":"paragraph","content":[{"text":"There were discussions about using the Media-Type header instead of a number in the uri. However, looking at a lot of major players in the api space, we decided to go with a global api version in the uri.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"ETag","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"(available with OpenMRS v1.8.1 or higher due to the Spring Framework 3.0.5 requirement)","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The module also adds an ETag to response headers when presenting resources to clients. ","type":"text"},{"text":"ETags","type":"text","marks":[{"type":"link","attrs":{"href":"http://en.wikipedia.org/wiki/HTTP_ETag"}}]},{"text":" have been implemented in shallow-mode (i.e. they save client bandwidth, but not server-side processing). As described ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.infoq.com/articles/etags"}}]},{"text":", as a client application you may want to look at ETag when making REST calls.","type":"text"}]},{"type":"paragraph","content":[{"text":"From the ","type":"text"},{"text":"wikipedia article","type":"text","marks":[{"type":"link","attrs":{"href":"http://en.wikipedia.org/wiki/HTTP_ETag"}}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"In typical usage, when a URL is retrieved the web server will return the resource along with its corresponding ETag value, which is placed in an HTTP \"ETag\" field:","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.migration","extensionKey":"__confluenceADFMigrationUnsupportedContentInternalExtension__","text":"","parameters":{"cxhtml":"

","block-inline":true,"nestedContent":{"type":"doc","content":[{"type":"codeBlock","content":[{"text":"ETag: \"686897696a7c876b7e\"","type":"text"}]}],"version":1}}}}]},{"type":"paragraph","content":[{"text":"The client may then decide to cache the resource, along with its ETag. Later, if the client wants to retrieve the same URL again, it will send its previously saved copy of the ETag along with the request in a \"If-None-Match\" field.","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.migration","extensionKey":"__confluenceADFMigrationUnsupportedContentInternalExtension__","text":"","parameters":{"cxhtml":"

","block-inline":true,"nestedContent":{"type":"doc","content":[{"type":"codeBlock","content":[{"text":"If-None-Match: \"686897696a7c876b7e\"","type":"text"}]}],"version":1}}}}]},{"type":"paragraph","content":[{"text":"On this subsequent request, the server may now compare the client's ETag with the ETag for the current version of the resource. If the ETag values match, meaning that the resource has not changed, then the server may send back a very short response with an HTTP 304 Not Modified status. The 304 status tells the client that its cached version is still good and that it should use that.","type":"text"},{"type":"hardBreak"},{"text":"However, if the ETag values do not match, meaning the resource has likely changed, then a full response including the resource's content is returned, just as if ETags were not being used. In this case the client may decide to replace its previously cached version with the newly returned resource and the new ETag.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Example using curl:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ curl -i -u admin:test http://127.0.0.1:8080/openmrs/ws/rest/v1/patient?q=Dar","type":"text"}]},{"type":"paragraph","content":[{"text":"RESPONSE HEADER IS:","type":"text"}]},{"type":"codeBlock","content":[{"text":"HTTP/1.1 200 OK\nExpires: Thu, 01 Jan 1970 00:00:00 GMT\nSet-Cookie: JSESSIONID=1jw2itu9oyt5v;Path=/openmrs\nContent-Type: application/json;charset=UTF-8\n*ETag: \"078c5b8fe25b332a40b4174bd38f5ee90\"*\nContent-Length: 399\nServer: Jetty(6.1.10)","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"$ curl -i -u admin:test http://127.0.0.1:8080/openmrs/ws/rest/v1/patient?q=Darius","type":"text"}]},{"type":"paragraph","content":[{"text":"RESPONSE HEADER IS:","type":"text"}]},{"type":"codeBlock","content":[{"text":"HTTP/1.1 200 OK\nExpires: Thu, 01 Jan 1970 00:00:00 GMT\nSet-Cookie: JSESSIONID=1jw2itu9oyt5v;Path=/openmrs\nContent-Type: application/json;charset=UTF-8\n*ETag: \"078c5b8fe25b332a40b4174bd38f5ee90\"*\nContent-Length: 399\nServer: Jetty(6.1.10)","type":"text"}]},{"type":"paragraph","content":[{"text":"We see that both the ETag are same and hence the client knows that the response would be the same and can save bandwidth.","type":"text"}]},{"type":"paragraph","content":[{"text":"After some days, if Darius's records have not been updated then, the client can send the ETag and check for modifications:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ curl -i -H 'If-None-Match:\"078c5b8fe25b332a40b4174bd38f5ee90\"' -u admin:test http://127.0.0.1:8080/openmrs/ws/rest/v1/patient?q=Darius","type":"text"}]},{"type":"paragraph","content":[{"text":"RESPONSE IS:","type":"text"}]},{"type":"codeBlock","content":[{"text":"HTTP/1.1 304 Not Modified\nExpires: Thu, 01 Jan 1970 00:00:00 GMT\nSet-Cookie: JSESSIONID=dlcztsmushgm;Path=/openmrs\nContent-Type: application/json;charset=UTF-8\nETag: \"078c5b8fe25b332a40b4174bd38f5ee90\"\nContent-Length: 0\nServer: Jetty(6.1.10)","type":"text"}]},{"type":"paragraph","content":[{"text":"From the ","type":"text"},{"text":"304 Not Modified","type":"text","marks":[{"type":"strong"}]},{"text":", we know that the records are the same and the client doesn't have to get the data again.","type":"text"}]}],"version":1}