API

RESTFul API in PhenoTips v. 1.2

RESTFul API in PhenoTips v. 1.3

The JSON representation of a patient and family records that is produced or that can be consumed by the PhenoTips RESTful API is specified in the JSON import/export and FamiliesJSON import/export section of the developer guide.

Accessing the service

The PhenoTips RESTful endpoint is rooted at the following URI:

http[s]://host[:port]/[applicationName]/rest/

For example, the list of patients in a PhenoTips instance running locally at port 8080 can be accessed via:

http://localhost:8080/rest/patients

Authentication

The PhenoTips RESTful API supports two types of authentication:

  • HTTP BASIC Auth: You provide your credentials using the Authorization HTTP header
  • PhenoTips session: If you are logged in and you use the cookies provided by the authentication mechanism, you will also be authenticated to the RESTful API. This is useful, for example, when you are interacting with the API using the XMLHttpRequest object of a browser using JavaScript.

If you don't provide any credentials, the RESTful API will return an Unauthorized (401) empty response for any attempt to access resources that require authentication.

Resources

Resource URIs are specified using URI templates. Bracketed elements are formal parameters and should be instantiated to actual values in order to retrieve the associated resource.

Using a REST client to test API endpoints

There are a number of REST clients that can be used to interact with the PhenoTips API. Typically, one can use a command-line tool or a browser addon to test API endpoints.

Command-line tools

While cURL is the most commonly used command-line tool for transferring data with URL syntax, httpie offers highly intuitive syntax designed to be a human-friendly alternative to cURL. 

Browser extensions

Browser extensions offer the ease of a simple user-interface for interacting with an API. To name a few, this includes selecting HTTP methods from a simple dropdown list, simple editing of request parameters, capability to add test cases, and pretty-print of output responses.

Recommendations

General steps

Authenticating with a REST client

This example uses a root URI running a PhenoTips instance locally on port 8080:

http://localhost:8080/rest
 

Via a browser extension:

Authentication parameters are inputted through the UI and are passed with each request. Authentication values can be saved and persisted between sessions as per user settings. 

Via httpie:

Send requests without having to specify login information each time by creating a session to have custom headers, authorization, and cookies persist with each request to your local PhenoTips instance.

http --session=JohnDoe -a JohnDoe:johndoespassword http://localhost:8080

Via curl:

curl -u JohnDoe:johndoespassword http://localhost:8080

Example response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Language: en
Content-Length: 22118
Content-Type: text/html;charset=UTF-8
Expires: Wed, 31 Dec 1969 23:59:59 GMT
Pragma: no-cache
Set-Cookie: JSESSIONID=1f7pvahulv2n7e2kp768r1kty;Path=/