SeattleClouds API Spec    
This topic is assigned to Timur

Apr 30, 2014 06:55 AM
SeattleClouds API Spec (PUBLISHERS)

SeattleClouds API Spec

v1.1.0


General Information


API Root URL: https://seattleclouds.com/api/v1



All requests submitting data should submit it in URL-encoded form (unless other form specified for specific API request) and must provide a Content-Type header.


Request content type:

Content-Type: application/x-www-form-urlencoded


All responses will provide HTTP status code and body containing resource document or an error in JSON format.


Response content type:

Content-Type: application/json; charset=UTF-8


All requests (except authentication token request) must be authenticated. Authentication is performed via the Authorization header which must be provided with every request.


Authorization header:

Authorization: SCAuth authToken={string}


Handling API Errors

The API returns two levels of error information:

  • HTTP error codes

  • A JSON object in the response body with additional details that can help you determine how to handle the error.


Examples


HTTP error code:

400 Bad Request


Response body:

{

 "error": {

   "errors": [

     {

       "reason": "missingFirstName",

       "message": "Missing parameter {firstName}"

     },

     {

       "reason": "invalidEmail",

       "message": "Email address is invalid"

     }

   ],

   "code": 400,

   "message": "One or more parameters are invalid or missing"

 }

}


Generic API error codes


Code

Message

Description

200

OK

Request succeeded.

201

Created

Request succeeded and a new resource was created as a result.

400

Bad Request

Request contains invalid or missing parameters.

401

Unauthorized

Request authentication failed.


Possible reasons:

  • missing or invalid authorization header;

  • missing, expired or invalid authentication token.


IMPORTANT: If you receive this error code and error reason is “invalidAuthToken” or “authTokenExpired” you should create a new authentication token via a corresponding API request and retry your original request with a new token.

403

Forbidden

You were not allowed to perform the request.


Possible reasons:

  • too many requests

  • not enough rights to access corresponding resource

  • invalid credentials provided while creating an authentication token

404

Not Found

Requested resource not found.


Possible reasons:

  • resource path/syntax is incorrect

  • the resource with provided ID doesn’t exist

500

Internal Server Error

There was an error during request processing. You can try again later.



Authentication tokens: create


REQUEST


HTTP request

POST auth/tokens


Parameters

none


Request body

Property name

Value

Description

Notes

Required Properties

username

string

Your seattleclouds.com account username.


password

string

Your seattleclouds.com account password.




RESPONSE


Response code

201 Created


Response body

{

  "authToken": {string},

  "expiresIn": {integer}

}


Property name

Value

Description

Notes

authToken

string

The authentication token (up to 255 characters long).


expiresIn

integer

The token expiration time in seconds (this is not guaranteed, so you must be prepared for earlier expiration).




Users: create


REQUEST


HTTP request

POST users


Parameters

none


Request body

Property name

Value

Description

Notes

Required Properties

email

string

The email address for new user. Must be unique per publisher/white label site.

max 50 characters

firstName

string

The first name for new user.

max 50 characters

lastName

string

The last name for new user.

max 50 characters



RESPONSE


Response code

201 Created


Response body

{

   "username": {string},

   "email": {string},

   "firstName": {string},

   "lastName": {string}

}


Property name

Value

Description

Notes

username

string

The username of created user.


email

string

The e-mail address of created user.


firstName

string

The first name of created user.


lastName

string

The last name of created user.




User authentication URLs: create


REQUEST


HTTP request

POST users/{username}/authUrls


Parameters

Parameter name

Value

Description

Required Parameters

username

string

The username of the user.



Request body

none


RESPONSE


Response code

201 Created


Response body

{

  "authToken": {string},

  "authUrl": {string},

  "expiresIn": {integer}

}


Property name

Value

Description

Notes

authToken

string

The user authentication token.


authUrl

string

The user authentication URL using authToken.


expiresIn

integer

The token expiration time in seconds (this is not guaranteed, so you must be prepared for earlier expiration).






Subscriptions: create


REQUEST


HTTP request

POST subscriptions


Parameters

Parameter name

Value

Description

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request body

Property name

Value

Description

username

string

The username of the user.

planName

string

The recurring subscription  plan name.

Valid values: Basic, Plus, Premium, Business, Enterprise, Ultimate

planAmount

string

The plan amount which is recurring amount to be charged from user every period of time (monthly).


NOTE: This parameter is optional. If {planAmount} is missing then it will be extracted from your publisher account settings.

paymentMethod

string

The payment method for subscription. Allowed values: self_managed.

paymentAmount

string

The total amount paid by user at subscription creation (first payment amount).


RESPONSE


Response code

201 Created


Response body

{

  "id": {string}

}



Subscriptions: read


REQUEST


HTTP request

GET subscriptions/{subscriptionId}


Parameters

Parameter name

Value

Description

Path Parameters

subscriptionId

string

The unique identifier of recurring subscription.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.



Request body

none


RESPONSE


Response code

201 Created


Response body

{

  {SubscriptionResource}

}


Subscription resource

Property name

Value

Description

id

string

The unique identifier of recurring subscription.

userName

string

The username of the user.

planAmount

string

The plan amount which is recurring amount to be charged from user every period of time (monthly).


NOTE: This parameter is optional. If {planAmount} is missing then it will be extracted from your publisher account settings.

planName

string

The recurring subscription plan name.

Valid values: Basic, Plus, Premium, Business, Enterprise, Ultimate.

subscriptionStatus

string

The subscription status. Valid values: active, cancelled.

lastPaymentAmount

string

The total amount paid by user at subscription creation (first payment amount).



Subscriptions: list


REQUEST


HTTP request

GET subscriptions


Parameters

Parameter name

Value

Description

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.

subscriptionStatus

string

The subscription status for subscription filtering.

Valid values: active, cancelled.



Request body

none


RESPONSE


Response code

201 Created


Response body

{

  "totalItems": {integer},

  "items": [ {SubscriptionResource} ]

}



Subscriptions: update


REQUEST


HTTP request

PUT subscriptions/{subscriptionId}


Parameters

Parameter name

Value

Description

Path Parameters

subscriptionId

string

The unique identifier of recurring subscription.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request body

Property name

Value

Description

planName

string

The recurring subscription  plan name.

Valid values: Basic, Plus, Premium, Business, Enterprise, Ultimate.

planAmount

string

The plan amount which is recurring amount to be charged from user every period of time (monthly).


NOTE: This parameter is optional. If {planAmount} is missing then it will be extracted from your publisher account settings.

paymentAmount

string

The total amount paid by user at subscription creation (first payment amount).

subscriptionStatus

string

The subscription status. Valid values: active, cancelled.


RESPONSE


Response code

200 OK


Response body

none




Subscription apps: add application to subscription


REQUEST


HTTP request

POST subscriptions/{subscriptionId}/apps


Parameters

Parameter name

Value

Description

Path Parameters

subscriptionId

string

The unique identifier of recurring subscription.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request body

Property name

Value

Description

appId

string

The application unique identifier from user applications list.


RESPONSE


Response code

201 Created


Response body

none





Subscription apps: list covered applications


REQUEST


HTTP request

GET subscriptions/{subscriptionId}/apps


Parameters

Parameter name

Value

Description

Path Parameters

subscriptionId

string

The unique identifier of recurring subscription.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request body

none


RESPONSE


Response code

200 OK


Response body

{

  "totalItems": {integer},

  "items": [ {string} ]

}


Subscription apps: remove application from subscription


REQUEST


HTTP request

DELETE subscriptions/{subscriptionId}/apps/{appId}


Parameters

Parameter name

Value

Description

Path Parameters

subscriptionId

string

The unique identifier of recurring subscription.

appId

string

The application unique identifier from user applications list

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request body

none


RESPONSE


Response code

200 OK


Response body

none


Applications: create


REQUEST


HTTP request

POST users/{username}/apps


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request body

Property name

Value

Description

appId

string

The new application identifier (unique per user). Only latin letters and digits allowed. It must be no longer than 50 characters.

platform

integer

The target platform of the application.

Valid values: 1 (Android), 2 (iPhone), 3 (iPad), 4 (Kindle), 5 (WebApp).

templateId

string

The identifier of starter application template (publisher website templates)


RESPONSE


Response code

201 Created


Response body

none



Applications: upload resources


REQUEST


HTTP request

POST upload/users/{username}/apps/{appId}


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

appId

string

The application unique identifier from user applications list.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request content type:

Content-Type: application/zip


Request body

binary - The content of application zip file to upload.



RESPONSE


Response code

200 OK


Response body

none


Applications: read


REQUEST


HTTP request

GET users/{username}/apps/{appId}


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

appId

string

The application unique identifier from user applications list.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.



Request body

none


RESPONSE


Response code

201 Created


Response body

{

  {ApplicationResource}

}


Application resource

Property name

Value

Description

id

string

The unique identifier of the application.

platform

integer

The target platform of the application.

Valid values: 1 (Android), 2 (iPhone), 3 (iPad), 4 (Kindle), 5 (WebApp)

uniqueId

string

The unique identifier of user application published on store (Apple App Store, Google Play, Amazon Appstore).


NOTE: This identifier is filled out by user when an application build is ordered.

title

string

The application title which is shown in the application list.

version

string

The application version (e.g: 1.0).

iconLink

string

The link to the application icon.

description

string

The application description.

resourcesSize

string

The size of the application resources.




Applications: list


REQUEST


HTTP request

GET users/{username}/apps


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.



Request body

none


RESPONSE


Response code

201 Created


Response body

{

  "totalItems": {integer},

  "items": [ {ApplicationResource} ]

}


Builds: read current build


REQUEST


HTTP request

GET users/{username}/apps/{appId}/builds/current


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

appId

string

The application unique identifier from user applications list.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.



Request body

none


RESPONSE


Response code

200 OK


Response body

{

   {BuildResource}

}


Build resource

Property name

Value

Description

id

string

The unique identifier of the application build.

platform

integer

The target platform of the application.

Valid values: 1 (Android), 2 (iPhone), 3 (iPad), 4 (Kindle), 5 (WebApp).

type

integer

The build type.

status

integer

The build status.

Valid values: 1 (New),  2 (Processing), 3 (Retry), 8 (Prepared),

10 (Completed), 11 (Failed), 12 (Rejected), 100 (Cancelled)

parameter

string

The build optional information.

buildBinaryUrl

string

The link to build binary.

appOwner.username

string

The username of app owner.

app.id

string

The unique identifier of the application.

publisher.id

string

The unique identifier of publisher account in SeattleCloud system.


Builds: create


REQUEST


HTTP request

POST users/{username}/apps/{appId}/builds


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

appId

string

The application unique identifier from user applications list.

Optional Query Parameters

publisherId

string

The unique identifier of publisher account in SeattleCloud system.


Request body

Property name

Value

Description

type

integer

Build type (optional).


Valid values:

1 - Instant Build

2 - Build & Review

3 - Build & Publish under my account

4 - Build & Publish under Publisher’s account

7 - Instant Ad Hoc


Default value: 1.


RESPONSE


Response code

201 Created


Response body

none


Cloud messages: create


REQUEST


HTTP request

POST users/{userName}/apps/{appId}/cloudMessages


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

appId

string

The application unique identifier from user applications list.

Optional Query Parameters

publisherId

string

Unique identifier of publisher account in SeattleCloud system.


Request body

Property name

Value

Description

Notes

Required Properties

module or type

string

One or another must be provided (read below).


Optional Properties

module

string

The module ID. Provide if the message is processed by a module. Do not provide if the message is processed by default SC module.

Either this or {type} must be provided.

type

string

The message type. Use this to differentiate between different message types for the same module.

Either this or {module} must be provided.

topics

string

Topic IDs list (separated by commas).

Allows targeting only devices subscribed to these topics of corresponding type.

data.*

string

The custom property where * is an arbitrary string. One message can contain any number of data.* properties (data.a, data.b, etc.)

Use this to pass message type-specific data.


Example for Announcement notification to all devices subscribed to topics

type=announcement&topics=Topic1,Topic2&data.message=Hello!

RESPONSE


Response code

201 Created


Response body

{

   {MessageResource}

}


Message resource

{

   "id": {string},

   "status": {string},

   "registrations": {

       "total": {integer},

       "processed": {integer}

   },

   "deliveryError": {

       "reason": {string}

   }

}


Message resource properties


Property name

Value

Description

Notes

id

string

The ID of the message.


status

string

The status of the message. Can be one of:

queued, processing, delivered, failed.


registrations.total

integer

The total number of registered devices. Can be -1 if total number is currently unknown. Otherwise it’s a non-negative integer number.


registrations.processed

integer

The total number of registrations processed (non-negative integer number). This number aggregates successful deliveries to actual devices, device unregistrations and other device specific delivery failures.


Optional Properties

deliveryError.reason

string

The delivery error reason. This property is only present if there was a serious issue with message delivery and all or most of the devices won’t be receiving the message.


Possible reasons that you can process:

payloadTooBig - the total message size (including custom parameters) is too big (retry with a smaller payload).


overCapacity - the server is too busy, retry later.


apnConfigurationError - Apple Push Notification system for the targeted app is not configured properly (for example APNs certificate is invalid or expired). This error is iOS specific.


There can also be other delivery errors, which are resolvable by retrying later.



Cloud messages: read


REQUEST


HTTP request

GET cloudMessages/{messageId}


Parameters

Parameter name

Value

Description

Path Parameters

messageId

string

The unique identifier of the cloud message.


Request body

none


RESPONSE


Response code

200 OK


Response body

{

  {MessageResource}

}


NOTE: cloud messages are periodically purged so you might receive a general API error with code 404, which means that there is no longer any information about this message.

EXAMPLES


Send Announcement push notification


REQUEST


HTTP request

POST users/{userName}/apps/{appId}/cloudMessages


Parameters

Parameter name

Value

Description

Path Parameters

username

string

The username of the user.

appId

string

The application unique identifier from user applications list.

Optional Query Parameters

publisherId

string

Unique identifier of publisher account in SeattleCloud system.


Request body

Property name

Value

Description

Notes

Required Properties

type

string

Must be equal to ‘announcement’


data.message

string

Your announcement message


Optional Properties

topics

string

Topic IDs list (separated by commas).

Allows targeting only devices subscribed to these topics of corresponding type.


Full body example:

type=announcement&topics=Topic1,Topic2&data.message=Hello!





Sample implementation for sending Announcement push notification in PHP

https://gist.github.com/anonymous/c617fb627da3a47ffe91




Apr 30, 2014 01:17 PM
Hi Dmitry,
thank you for this information,
Can you give us some examples of how we can use seattleclouds api?

Thanks,
Daniel
Hello Daniel,

Please note that the API features are available only for Publisher subscribers. You, as a business subscriber, will not be able YET to use it because all the available functions are related to publisher website.

Regards,
Aurel



Dec 04, 2014 11:53 PM
Hello Daniel, 

We're getting error "Authentication Failed: Invalid Credentials" when send request to https://seattleclouds.com/api/v1/auth/tokens with passing username and password as post.  Do u know what is meaning of it?
Kevin, please open a support ticket for any related issues.


Jan 26, 2015 03:31 AM
how about push notification api?
Hafiz, please open a related support ticket for more info.


Mar 09, 2015 08:48 AM
Hafiz,

Above specification has been updated with Cloud Messaging API resources.


Oct 15, 2015 05:33 AM
We've added a more specific example of how to send Announcement push notification using the API and a basic implementation of this request in PHP.


Nov 24, 2015 11:34 AM
Updated to include API resources for managing app subscriptions and plans. Note that these API resources are only available to white-label publishers.


Nov 24, 2015 12:19 PM
Updated to include API resources for managing applications and builds. These API resources are available to everyone and are currently in beta. Please report any issues.


Mar 01, 2016 10:13 PM
Please, move the thread to forum Publishers space. Thank you.

Regards


Feb 10, 2017 03:05 AM
Hello. In order to obtain auth token (auth/tokens) I need username and password. 

How to find out username & password if I use facebook to login seattleclouds?

    1