Difference between revisions of "The Lookup Table Modification API"

From MircWiki
Jump to navigation Jump to search
 
(7 intermediate revisions by the same user not shown)
Line 12: Line 12:
 
Note, this API requires that the DicomAnonymizer stage have an <b><tt>id</tt></b> attribute.
 
Note, this API requires that the DicomAnonymizer stage have an <b><tt>id</tt></b> attribute.
  
To be effective, the key must include both the KeyType and the PHI value. For example:
+
Note also that the key must include both the KeyType and the PHI value. For example:
  
:<b><tt>http://192.168.0.4:8080/lookup?id=TEST&key=ptid/567&value=777</tt></b>
+
:<b><tt>http://ip:port/lookup?id=TEST&key=ptid/567&value=777</tt></b>
  
 
adds the <b><tt>ptid/567</tt></b> entry to the table and assigns it the value <b><tt>777</tt></b>.
 
adds the <b><tt>ptid/567</tt></b> entry to the table and assigns it the value <b><tt>777</tt></b>.
  
The LookupServlet supports this API through both the HTTP GET and PUT methods. GET is supported only to make initial testing easy. Developers are encouraged to implement using the PUT method as the GET support will be removed in the near future.
+
The LookupServlet supports this API through HTTP PUT method only.
  
 
The servlet returns one of these response codes:
 
The servlet returns one of these response codes:
 
* 200: OK - the update succeeded.
 
* 200: OK - the update succeeded.
* 403: Forbidden - the requesting user is either not authenticated or does not have the admin role.
+
* 403: Forbidden - the requesting user is either not authenticated or does not have the <b><tt>admin</tt></b> role.
 
* 304: Not modified - the request could not be serviced with the supplied parameters.
 
* 304: Not modified - the request could not be serviced with the supplied parameters.
  
The Not modified response can occur if any one of these conditions are met:
+
The 304 response can occur if any one of these conditions are met:
 
* any of the three parameters are missing
 
* any of the three parameters are missing
 
* the <b><tt>id</tt></b> parameter does not reference a registered PipelineStage
 
* the <b><tt>id</tt></b> parameter does not reference a registered PipelineStage
 
* the <b><tt>id</tt></b> parameter references a PipelineStage that is not a DicomAnonymizer
 
* the <b><tt>id</tt></b> parameter references a PipelineStage that is not a DicomAnonymizer
  
If the update succeeds, the servlet returns the text <b><tt>OK</tt></b>; otherwise, the response is empty.
+
The request must include sufficient information to authenticate the user as having the <b><tt>admin</tt></b> role. There are three ways to do that:
 +
* Supply an RSNA header containing the credentials of an admin user in clear text:
 +
: <b><tt>RSNA username:password</tt></b>
 +
* Supply an Authorization header with basic auth credentials as specified in [[http://www.ietf.org/rfc/rfc2617.txt http://www.ietf.org/rfc/rfc2617.txt]]:
 +
: <b><tt>Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==</tt></b>
 +
* Supply the credentials to the CTP LoginServlet, obtain the <b><tt>RSNASESSION</tt></b> cookie, and supply the cookie in requests.
 +
 
 +
If the update succeeds, the servlet returns the text <b><tt>OK</tt></b> with <b><tt>Content-Type=text/plain;charset=UTF-8</tt></b>; otherwise, the response is empty.

Latest revision as of 13:43, 25 June 2015

This article describes how to update the DICOM Anonymizer lookup table through an external program. The intended audience of this article is software developers. See The CTP Lookup Table Editor for a description of the lookup table structure.

An external program can add or modify a single entry in the lookup table for a DicomAnonymizer stage by accessing the CTP LookupServlet with this URL path:

/lookup?id=...&key=...&value=...

where:

  • id is the id attribute of the DicomAnonymizer stage whose lookup table is to be modified
  • key is the key of the lookup table entry to be created or modified
  • value is the value to be assigned to the key

Note, this API requires that the DicomAnonymizer stage have an id attribute.

Note also that the key must include both the KeyType and the PHI value. For example:

http://ip:port/lookup?id=TEST&key=ptid/567&value=777

adds the ptid/567 entry to the table and assigns it the value 777.

The LookupServlet supports this API through HTTP PUT method only.

The servlet returns one of these response codes:

  • 200: OK - the update succeeded.
  • 403: Forbidden - the requesting user is either not authenticated or does not have the admin role.
  • 304: Not modified - the request could not be serviced with the supplied parameters.

The 304 response can occur if any one of these conditions are met:

  • any of the three parameters are missing
  • the id parameter does not reference a registered PipelineStage
  • the id parameter references a PipelineStage that is not a DicomAnonymizer

The request must include sufficient information to authenticate the user as having the admin role. There are three ways to do that:

  • Supply an RSNA header containing the credentials of an admin user in clear text:
RSNA username:password
Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
  • Supply the credentials to the CTP LoginServlet, obtain the RSNASESSION cookie, and supply the cookie in requests.

If the update succeeds, the servlet returns the text OK with Content-Type=text/plain;charset=UTF-8; otherwise, the response is empty.