Upcoming Backward Incompatible Changes to WMS APIs
OCLC will be installing an update to the following APIs on July 9, 2017:
- WMS Availability
- WMS Collection Management API
- WMS NCIP - Staff Profile
We want to call out specifically to the developer community that customers using either of the following APIs
- WMS Collection Management API
- WMS NCIP - Staff Profile
will need to update their code to deal with backwards-incompatible changes within this update. Specifically a security enhancement for user information. This user information (principalID and principalIDNS) which previously could be passed via url query parameters must now be passed via either:
- the Authorization header
- an Access Token associated with the user
Additionally, this update includes upgrades to the underlying API infrastructure to align it with current API practices and patterns and enhance the security of our APIs.
Note: the current version of the WMS Collection Management API supports sending user information via the header as well as the url. Therefore, institutions can update their code which users this API prior to the July install.
Examples of Deprecated API Calls
WMS NCIP Staff Profile
POST /ncip?inst=128807&principalID={principalID}&principalIDNS=urn:oclc:wms:da HTTP/1.1 Host: circ.sd00.worldcat.org Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="{api-key}", timestamp="1491947044", nonce="e3d821e5", signature="naIA0zVUnphaIcc5Bt9BIpnfPAh4BzQh5pc0Ar3WZG0="
WMS Collection Management API
GET /LHR?q=oclc:33252178&principalID={principalID}&principalIDNS=urn:oclc:wms:da HTTP/1.1 Host: circ.sd00.worldcat.org Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="api-key}", timestamp="1491946771", nonce="6e46e500", signature="tsKo2PwzDVY5sybjI3SuWUBR3Ola5huPGoPyOB/KgRU="
Example new API Calls
WMS NCIP Staff Profile
POST /ncip HTTP/1.1 Host: circ.sd00.worldcat.org Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="{api-key}", timestamp="1491947044", nonce="e3d821e5", signature="naIA0zVUnphaIcc5Bt9BIpnfPAh4BzQh5pc0Ar3WZG0=", principalID="{principalID}", principalIDNS="urn:oclc:wms:da"
WMS Collection Management API
GET /LHR?q=oclc:33252178&principalID={principalID}&principalIDNS=urn:oclc:wms:da HTTP/1.1 Host: circ.sd00.worldcat.org Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 clientId="api-key}", timestamp="1491946771", nonce="6e46e500", signature="tsKo2PwzDVY5sybjI3SuWUBR3Ola5huPGoPyOB/KgRU=", principalID="{principalID}", principalIDNS="urn:oclc:wms:da"
Labeling Applications
This change regarding user information will impact several formally and informally shared labelling applications developed by the WMS community. The code for these applications will need to be updated and new versions installed after the July 9 upgrade. The OCLC Platform Team has been in touch with several institutions who have contributed to these projects in order to inform them about the API change and work with them to update their code. Additionally, we are investigating other ways to support community members using these applications during the transition.
-
Karen Coombs
Senior Product Analyst