Page tree
Skip to end of metadata
Go to start of metadata
This document describes the API of the security part, that allows for example to login and log out a user.

Resources

Create Security Session (Log in)

This resource allows you to create a new security session, or in other words to log in at the platform. With a successful login, a security session will be created at the platform for you, and the security sessionId will be returned in the location header. You can use this security sessionId to access sessionId protected resources, such as user resources (see SprdAuth protocol for more information). Use HTTPS when conducting requests on this resource.

Denial of Service protection

Please note that we implemented a Denial of Service protection for session creation. In general, too many login attempts (at the time of writing more than 2 attempts per 10 seconds) from the same origin IP address can make this IP address being blacklisted for a certain time frame, resulting in HTTP 500 responses. The exact scheme is constantly subject of change without prior notice. See https://forum.spreadshirt.net/threads/26954-API-session-500-error for more information.

Url

.../v1/sessions

Sample

https://api.spreadshirt.net/api/v1/sessions

Type

List

Method

POST

Special Status Codes

 

Request Representation:

<login xmlns:xlink="http://www.w3.org/1999/xlink" 
       xmlns="http://api.spreadshirt.net">   
   ...
</login>

See Login Representation

Response Representation:

Header:

Location: .../v1/sessions/70aab75c0b6217c2aff1fe301111929291

Retrieve Security Session

This resource allows to check whether a security session exists.

Url

.../v1/sessions/{sessionId}

Sample

http://api.spreadshirt.net/api/v1/sessions/70aab75c0b6217c2aff1fe301111929291

Type

Entity

Method

GET

Special Status Codes

 

APIKey

 

SessionId

 

Response Representation:

<session>
   ...
</session>

See Session Representation

Delete Security Session (Log out)

This resource allows you to delete an open security session, or in other words to log out at the platform. Please note that security sessions also expire automatically if the session is no longer used.

Url

.../v1/sessions/{sessionId}

Sample

http://api.spreadshirt.net/api/v1/sessions/70aab75c0b6217c2aff1fe301111929291

Type

Entity

Method

DELETE

Special Status Codes

 

Representations

Login

Field

Description

login

 

login/username

Your Spreadshirt login or e-mail address. (userId not supported anymore)

login/password

The plain text password of your Spreadshirt user.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<login xmlns:xlink="http://www.w3.org/1999/xlink"      
       xmlns="http://api.spreadshirt.net">   
   <username>the e-mail address</username>
   <password>the password</password>
</login>

Session

Field

Description

session

Representation of a platform session.

session/user

Reference to the user that the session belongs to.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<session xmlns="http://api.spreadshirt.net"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xlink:href="http://api.spreadshirt.net/api/v1/sessions/26bdd278-b678-4ccc-931e-0a26d30befeb"
         id="26bdd278-b678-4ccc-931e-0a26d30befeb">
    <user xlink:href="http://api.spreadshirt.net/api/v1/users/1102730" id="1102730"/>
</session>

Use Cases

Log in and Access Protected User Products List

1. + 2. Retrieve User Products List without valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=...

Status Code: 401 (sessionId does not exist - means user not logged in!)

3. + 4. Log in/ Create Security Session

Resource: POST .../sessions

Request Representation:

<login xmlns:xlink="http://www.w3.org/1999/xlink"      xmlns="http://api.spreadshirt.net">   <username>Spreadshirt</username>
   <password>spreadshirt</password>
</login>

Status Code: 201 Session Created (Logged in)

Response Representation:

Header:

Location: .../sessions/456

5. + 6. Retrieve User Products with valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=456

Status Code: 200

Response Representation:

<products...>
   ...
</products>

Logout and Access Protected User Products List

1. + 2. Retrieve User Products List with valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=456

Status Code: 200

Response Representation:

<products...>
   ...
</products>

3. + 4. Logout/ Delete Security Session

Resource: DELETE .../sessions/456

Status Code: 200 (Logged out/ Deleted session)

5. + 6. Retrieve User Products List without valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=...

Status Code: 401 (sessionId does not exist - means user not logged in!)

  • No labels