Sonos Music API - Getting Started Guide

Introduction to SOAP

SMAPI is built over SOAP. SOAP is a platform and language independent communication protocol using XML and XML namespaces. SOAP is used in conjunction with WSDL files that also use XML to define message formats and the mechanisms Web services can use to access them; essentially the interface contract between the Web service and clients using it. Both SOAP and WSDL are defined by the World Wide Web Consortium (better known as W3C), the same group that maintains HTML and many other internet standards.

SOAP messages are contained within a SOAP envelope which must be the root element of the XML sent over the wire. The envelope contains an optional header and a required body element. The header must be the first element within the envelope if present and contains directives related to the message. It should not be confused with HTTP headers which may also be part of the overall request. The body either contains the message content in a format defined by the Sonos WSDL file or contains fault elements conveying error information.

In other words, the general syntax of the envelope is:

<[soap]:Envelope
xmlns:[soap]="http://schemas.xmlsoap.org/soap/envelope/">
  <[soap]:header>[header]</[soap]:header>
  <[soap]:body>[body]</[soap]:body>
</[soap]:Envelope>

where [header] is the content of the SOAP header and [body] is the SOAP body.

All of the elements within a SOAP message use XML namespaces to indicate where specific elements are defined. The envelope element must include a namespace definition pointing to the universal soap namespace URI (http://schemas.xmlsoap.org/soap/envelope/) and elements within the message typically use a namespace pointing to a public, online version of the WSDL file defining the included elements or to a public namespace URI representing the elements of the namespace. In the latter case, the URI is symbolic and does not need to actually load a copy of the definitions; both parties understand that namespaces pointing to the URI contain the elements defined in a specific WSDL file defined elsewhere.

In some cases, more than one namespace is needed to fully express the elements within the body of a single message. This is perfectly valid as long as all namespaces are defined and each element explicitly indicates the proper namespace in its declaration. The Sonos public namespace URI is http://www.sonos.com/Services/1.1. This includes the SMAPI version number (1.1). The related Sonos Music API WSDL file can be found on Sonos Labs.

For more information on WSDL files, see this tutorial or the official WSDL specifications:

http://www.w3schools.com/xml/xml_services.asp
http://www.w3.org/TR/wsdl

For more information on SOAP, see this tutorial or the official SOAP specifications:

http://www.w3schools.com/xml/xml_soap.asp
http://www.w3.org/TR/soap/