Version: 2012.02.15

Krames StayWell External Web Service Documentation

Introduction

Intended Audience

The intended audience of this Web Services documentation includes software engineers, web designers and quality assurance engineers who develop, maintain and test software that will interface with the StayWell external content Web Services.

Getting Started

To begin, click on one of the method usage examples listed on the navigation bar displayed at the left of this page, then follow the instructions provided on the example page.

This documentation is divided up into three main sections:

  • Best Practices - identifies best practices in dealing with the Krames StayWell Web Services
  • Common Usage Scenarios - identifies common implementation tasks when working with the Krames StayWell Web Services
  • Method Documentation - provides detailed documentation on the specific usage of each Web Service method in the Krames StayWell Web Service API

Introduction

The Krames StayWell Web Service interface allows clients to:

  • Retrieve content with associated metadata
  • Execute searches for content
  • Retrieve lists of content related to other content or a set of MeSH concepts
  • Retrieve images referenced by content
  • Retrieve collections of content organized into tree structures
  • Prevent specific content from being returned to end-users

All responses (except images) are encoded as XML and conform to our published schemas. The markup contained in our content is based on xhtml to simplify display transformations. This markup is described on the Schema Glossary page.

In order for a client to access the Krames StayWell Web Services, a license for that client needs to be set up in our content repository. The license will be identified by a short alphanumeric string called the SiteName. The license defines which content is available to the client. The SiteName must be included in the URL of all Web Service requests.

Licenses can be created in a hierarchy. The SiteName can have subsites appended, separated with a forward slash character; e.g. "ClientGroup/ClientA". Any number of subsites can be appended. Invalid subsites and/or invalid nesting of sites will cause authentication errors on Web Service calls.

Authentication/Authorization

To authenticate Web Service callers, in addition to including the SiteName, the IP address of the caller is compared with a list of registered IP addresses for that license. Therefore, a client must supply the list of IP addresses for their own servers which will be making Web Service calls. This list must include the IP addresses for any necessary development and testing servers. Remember to supply the IP addresses as seen by our servers. For instance, if traffic originating from your server is passed through a NAT device, we need the IP address of its external interface. To assist StayWell in managing the licenses for Web Service clients, each IP address registered must have a short description attached such as “in-house development server”, “developer workstation”, etc.

General Usage

The Web Services are available at URLs under: http://external.ws.StayWell.com/[SiteName]/ (where [SiteName] would be substituted with the appropriate value for the client license).

The Schema that defines the XML structure of the Content.svc responses can be found at http://external.ws.StayWell.com/DocumentationV2/Content.xsd.

The Schemas which define the XML structure of the old document requests and responses can be found at http://external.ws.StayWell.com/DocumentationV2/Types.xsd and http://external.ws.StayWell.com/DocumentationV2/Markup.xsd

If the client wants to use SOAP, the WSDL file is located at http://external.ws.StayWell.com/DocumentationV2/Services.wsdl. Please note that these methods are deprecated and their use is highly discouraged.

Client authentication is not required to access the .wsdl and .xsd files. A SiteName will be necessary to access the .wsdl file.

Attempts to actually execute Web Service calls from a non-authenticated caller will result in a “403 Forbidden” response status.

In extenuating circumstances, you could experience “500 Internal server error” responses, such as during server maintenance.

If the server cannot interpret the HTTP request, a “400 Bad Request” response is generated. This could happen if the service name or method name is incorrect, or the wrong number or names of parameters have been supplied.

The Web Services can be accessed using HTTP GET and two kinds of HTTP POST requests. Clients are encouraged to use HTTP GET or HTTP POST (with raw XML) to simplify XML processing.

Regardless of the request type, all Web Service calls use the same URL structure:

  • http://external.ws.StayWell.com/[SiteName]/[ServiceName]/[MethodName]
  • [SiteName] as described above.
  • [ServiceName] will contain the name of the Web Service class being accessed. Currently the choices are "Content.svc", "Documents.svc", "Blocking.svc" and "Collections.svc". All new methods are in the "Content.svc" service, the others will be phased out over time.
  • [MethodName] will contain the name of the Web Service method being accessed.
  • The response to all method calls will be an XML document with contents from the namespace URIs http://ws.StayWell.com and http://ws.StayWell.com/markup.

HTTP GET Requests

  • The input values for the method's parameters (if any) are supplied in the “query string”
    ParameterName=Value&ParameterName2=Value
  • The parameters for each method are detailed in each method's page on this site.
  • The response status code will always be 200 if the server actually received and processed the request. Errors encountered during the processing of the request can be detected by looking at the response XML. The root element will be “<Errors>”.
  • This request type can be used to call methods with any number of parameters.

HTTP POST Requests

  • The Content-Type HTTP header indicates which of the two “POST” request types is being used.
  • If it is text/xml, the request body is used unchanged for the value of the single parameter to the method. This request type can be used to call methods with zero or one parameter.
  • If it is application/x-www-form-urlencoded, the request body is used the same way as the query string for a GET request. This request type can be used to call methods with any number of parameters.
  • The response status code will always be 200 if the server actually received and processed the request. Errors generated during the processing of the request can be detected by looking at the response XML. The root element will be “<Errors>”.

SOAP Requests
NOTE: The use of these SOAP methods is highly discouraged.

  • These methods are deprecated and because of this they are no longer being updated to take advantage of recent updates to the repository.
  • SOAP calls, as indicated in the WSDL, use a document/literal style as opposed to RPC/encoded.
  • SOAP 1.1 - http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
  • WS-I Basic Profile 1.0 - http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html
  • Are detected by the presence of a SOAPAction HTTP header in the request.
  • Can be used to call methods with zero or one parameter.
  • Must be properly formatted SOAP requests, otherwise the HTTP response status will be 400 “Bad Request”.
  • The contents of the soap:Body element are supplied as the single parameter.
  • Errors will be returned as standard SOAP “faults”