Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


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


Code Block
titleAdding a person name
POST /ws/rest/person/uuidofperson/namesname
Body content:
{"givenName": "John", "familyName": "Smith"}
Code Block
titleEditing a person's name
POST /ws/rest/person/uuidofperson/namesname/uuidofname
Body content:
{"givenName": "Johnny"}


  • For resource,
    • GET /ws/rest/resource?q=query = search
    • GET /ws/rest/resource/uuid = retrieve
    • POST /ws/rest/resource = create
      • Request body contains data to persist (not in request params)
    • POST /ws/rest/resource/uuid = partial update of the resource
      • Request body contains just the fields to update (not in request params)
    • PUT = replace value of entire object (we don't use this yet)
    • DELETE /ws/rest/resource/uuid = void for data, retire for metadata
    • DELETE /ws/rest/resource/uuid?purge=true = purge (aka delete from the database entirely)
  • Do not put verbs into the URL. Represent this idea with sub-resources.
    • For example, instead of addNameToPerson we POST to /ws/rest/person/uuid/names
  • URLS:
    • Are prefixed with /ws/rest/ due to servlet forwarding in openmrs
    • All lowercaseThe URL should be written in all-lowercase ASCII letters
    • No special characters (e.g. no spaces or underscores)
    • Hyphens are ok if absolutely necessary
    • No extensions allowed (acceptHeader will be used to specify json or xml content. All json for release 1.0)
  • Sub-resources (i.e. things like personname or patientidentifier which belong to a parent resource) should have their URIs inside the URI of their parent (like /ws/rest/person/uuid/names/nameuuid)
  • Domain objects that are separately managed get their own URI. (e.g. /ws/rest/enrollment/uuid instead of /ws/rest/program/uuid/enrollments/uuid)
  • Hide (aka don't expose) "helper" classes as much as possible (e.g. web service clients should never see ConceptSet, etc)
  • Resource names should usually be the same as the domain objects they represent, but they may differ if the domain object name is confusing.
    • For example org.openmrs.PatientProgram is /ws/rest/enrollment


Currently only BASIC authentication is supported.  Header arguments values of ___ and ___ are expected. 

Alternatively, a session token can be used.  GET /openmrs/ws/rest/session with the BASIC credentials will return the current token value.  This token should be passed with all subsequent calls as a cookie named jsessionid=token.