REST Resources

This API supports a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations. The following resources are accessible through the RESTful model:

There is also a WADL document describing the REST API.

User guide

SOWPROG API

SOWPROG API is a set of web services allowing you to search, create, update :

Test environment is available here : http://test.api.sowprog.com/api/v1/

All services can be accessed using JSON or XML.

Authentication

Authentication is based on OAuth2
You must first authenticate your application then the user on behalf of whom you will use the API.
OAuth2 password and refresh token are implemented for now.

Test environment does not provide SSL. Production environment does and request must be made through https.

Please contact us to get an access.

get an access token

POST to http://test.api.sowprog.com/api/v1/token using Basic auth related to the application and user login and password as parameters. 

Example :
POST /api/v1/token HTTP/1.1
Host: test.api.sowprog.com
Authorization: Basic XXX
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=XXX&password=XXX


Response :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuth>
    <access_token>XXX_UUID</access_token>
    <expires_in>3600</expires_in>
    <token_type>bearer</token_type>
    <refresh_token>XXX_UUID</refresh_token>
</OAuth>

Use the access token to access other services of the API

Example :
GET /api/v1/account HTTP/1.1
Host: test.api.sowprog.com
Authorization: bearer XXX_acces_token_XXX


Réponse :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<userResponse>
    <user>
        <sowprogId>
            <id>5582</id>
            <version>3</version>
            <deleted>false</deleted>
            <creationDate>1421155275782</creationDate>
            <modificationDate>1421155275797</modificationDate>
        </sowprogId>
        <link>
            <href>http://test.api.sowprog.com/api/v1/account</href>
            <method>GET</method>
            <rel>self</rel>
        </link>
        <email>amicki+admin_api@gmail.com</email>
        <status>VALIDATED</status>
        <role>ADMINISTRATOR</role>
    </user>
</userResponse>

Exploring the API

Start with a GET on the root of the api : http://test.api.sowprog.com/api/v1/
You will get a list of links providing the allowed actions.
These links are available on each resources.

Example, for an event, you can take the following actions :
...
 	<link>
            <href>http://test.api.sowprog.com/api/v1/events/65511</href>
            <method>GET</method>
            <rel>self</rel>
        </link>
        <link>
            <href>http://test.api.sowprog.com/api/v1/events/65511</href>
            <method>PUT</method>
            <rel>update</rel>
        </link>
...

self is the current URI.
update tells you that to update an event, you have to send a PUT to http://test.api.sowprog.com/api/v1/events/65511

Errors

Response status is 200 when everything is fine.
If a problem occurs, the status can be :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<message>
    <errorMessages>
        <errorCode>MANDATORY_ELEMENT</errorCode>
        <element>eventDescription.title</element>
    </errorMessages>
    <errorMessages>
        <errorCode>MANDATORY_ELEMENT</errorCode>
        <element>eventDescription.description</element>
    </errorMessages>
    <errorMessages>
        <errorCode>MANDATORY_ELEMENT</errorCode>
        <element>eventDescription.punchline</element>
    </errorMessages>
</message>

If the error code is BAD_FORMAT, a field expectedFormat will give you the expected format.

Formats : JSON ou XML

Use the header to tell if you'd like to work in XMLor JSON

Accept: application/xml ou application/json
Content-Type: application/xml ou application/json

A complete example

Create an event

POST /api/v1/events HTTP/1.1
Host: test.api.sowprog.com
Authorization: bearer XXX_access_token_XXX
Accept: application/xml
Content-Type: application/xml

    <event>
        <cancelled>false</cancelled>
        <eventDescription>
            <title>Nouveau via API éè - title</title>
            <punchline>Nouveau via API éè - punchline</punchline>
            <description>Nouveau via API éè - Description</description>
            <pictureCredit>Nouveau via API éè - pictureCredit</pictureCredit>
            <eventType>
                <sowprogId>
                    <id>4</id>
                </sowprogId>
            </eventType>
            <eventStyle>
                <sowprogId>
                    <id>52</id>
                </sowprogId>
            </eventStyle>
        </eventDescription>
        <offer>
            <freeAdmission>false</freeAdmission>
            <eventPrice>
                <label>Tarif plein</label>
                <price>30</price>
                <currency>EUR</currency>
            </eventPrice>
            <eventPrice>
                <label>Tarif DanseAujourdhui</label>
                <price>19</price>
                <currency>EUR</currency>
            </eventPrice>
            <eventTicketStore>
                <label>Réserver avec DanseAujourdhui</label>
                <url>http://www.danseaujourdhui.fr/recommandations/saison-2014-2015/robyn-orlin-finger/</url>
            </eventTicketStore>
        </offer>
        <eventSchedule>
            <eventScheduleDate>
                <startHour>20:30</startHour>
                <endHour>22:00</endHour>
                <date>2015-01-13</date>
                <soldOut>false</soldOut>
            </eventScheduleDate>
            <eventScheduleDate>
                <startHour>20:30</startHour>
                <endHour>22:00</endHour>
                <date>2015-01-14</date>
                <soldOut>false</soldOut>
            </eventScheduleDate>
        </eventSchedule>
        <partOfEventGroup>false</partOfEventGroup>
        <artist>
            <artist>
                <sowprogId>
                    <id>17471</id>
                </sowprogId>
            </artist>
            <sequence>0</sequence>
            <billing>HEADLINE</billing>
        </artist>
        <location>
            <sowprogId>
                <id>502</id>
            </sowprogId>
        </location>
    </event>

Add a picture

PUT /api/v1/events/65511/picture HTTP/1.1
Host: test.api.sowprog.com
Authorization: bearer XXX_access_token_XXX
Accept: application/xml

----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="file"; filename="1br.JPG"
Content-Type: image/jpeg


----WebKitFormBoundaryE19zNvXGzXaLvS5C

Publish the event

PUT /api/v1/events/65511 HTTP/1.1
Host: test.api.sowprog.com
Authorization: bearer XXX_access_token_XXX
Accept: application/xml
Content-Type: application/xml

    <event>
        <sowprogId>
            <id>65511</id>
            <version>4</version>
        </sowprogId>
        <status>PUBLISHED</status>
    </event>

Update an event

When updating a resource, unspecified fields are not modified. Fields provided without value are taken into account.
In the previous example, only the status was updated.
If the provided data is : 

 
    <event>
        <sowprogId>
            <id>65511</id>
            <version>4</version>
        </sowprogId>
        <status>PUBLISHED</status>
	<eventDescription>
		<title>Titre modifié</title>
	</eventDescription>
    </event>

The title is also updated.

If the provided data is : 

    <event>
        <sowprogId>
            <id>65511</id>
            <version>4</version>
        </sowprogId>
        <status>PUBLISHED</status>
	<eventDescription>
		<title></title>
	</eventDescription>
    </event>

You will get an error saying the title is mandatory.

Data Model

All endpoints act on a common set of data. The data can be represented with different media (i.e. "MIME") types, depending on the endpoint that consumes and/or produces the data. The data can described by XML Schema, which definitively describes the XML representation of the data, but is also useful for describing the other formats of the data, such as JSON.

This document will describe the data using terms based on XML Schema. Data can be grouped by namespace, with a schema document describing the elements and types of the namespace. Generally speaking, types define the structure of the data and elements are instances of a type. For example, elements are usually produced by (or consumed by) a REST endpoint, and the structure of each element is described by its type.

Namespace "ns0"

Namespace URI: (default namespace)
XSD: ns0.xsd

Data Elements

Data Types