Back to top

This is the offical stomt documentation.

Request/Response format 

This is the standard Response format. Read this first.

To keep the API endpoint flexible, maintainable and extendable, we defined a standard set of custom HTTP headers and a fix output format. In this section you’ll learn how requests are build and how responses will always look like.

Current state is RFC (Request for comments).

Launch for this API version is planned for the 20th of November ‘14.

Standard Request Headers

  • appid Contact Philipp for yours.

  • userlang ISO 639-1 formatted language. Supported: de, en. Use browser language if guest.

  • devicetype Users device format

    • Smartphones: web_mobile, android_mobile, ios_mobile
    • Tablets: web_tablet, android_tablet, ios_tablet
    • Desktop: web_desktop

Some attributes are flagged with (web) or (native) which means that they are only sent with on web/native calls. Methods marked with [LOGIN REQUIRED] need the following HTTP headers:

  • accesstoken You’ll receive one after login

  • userid Users HASH-ID. See Auth section

These headers should always be sent if possible. In the following documentation we’ll only mention additional headers on top of these:

    accesstoken:  (string)  // If the user is logged in
    userid:       (string)  // If the user is logged in
    userlang:     (string)  // required | ISO 639-1 | e.g. 'en'
    devicetype:   (string)  // required | see above | e.g. 'ios_mobile'

Standard Response Format

  • Will always return HTTP status 200
  • Will always return content-type application/json

Take a look into the comments for further information.

    {
       // Always | Some meta information
       'meta' : {
          'amountItems': (integer),          // Always | Amount of items in data-attribute
          'amountNotifications': (integer),  // Optional | Only if notifications exist
          'serverTime': (integer)            // Always | UNIX Timestamp with server time
       },

       // Always | Contains the result
       'data' : [],

       // Optional | Only if unseen notifications are available
       'notifications': [],      // Notification - always Array - see below

       // Optional | Only if error occurs
       'error' : {
          'status' :  (integer),  // the 'real' HTTP Status code
          'msg' :     (string)    // Human readable error message
       }
    }

notification 

You don’t get notifications through a separate GET request. You get them delivered within each normal request.

You can find them under the notifications-attribute in the standard response format (see above).

This is how they look like:

  [
    {
        'id':       (integer),
        'text':     (string),    // Just display the text linking to the goal

        'goal': {
          'slug':   (string)(web), // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
          'type':   (string),    // Type: may be a target or a stomt
          'id':     (string)     // Hashed goal id
        },

        'ago' :     (string),    // "x minutes ago" - currently English only
        'seen':     (integer),   // null = unseen; (unix timestamp) = seen
        'clicked':  (integer)    // null = unclicked; (unix timestamp) = clicked
    }
  ]

Set notifications as seen/clicked 

If notifications are seen by the user (The user clicked on the notifications symbol) set the seen-attribute to the current unix timestam (e.g. 1409835266).

If the user clicks/taps on a notification set the clicked-attribute to current unix timestamp.

Set the notification to clicked or seen
/notifications/

[LOGIN REQUIRED]

  • Request
  • Headers
    Content-Type: application/json
    Body
    [
    {
        'id' : (integer),
        'text' : (string),
    
        'goal' : {
          'slug':  (string)(web), // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
          'type'  :  (string),
          'id':  (string)
        },
    
        'ago' : (string),       // "x minutes ago" - currently English only
        'seen': (integer)       // null = unseen; (unix timestamp) = seen
        'clicked': (integer)    // null = unclicked; (unix timestamp) = clicked
    }
    ]
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
    {
        'id' : (integer),
        'text' : (string),
    
        'goal' : {
          'slug':  (string)(web), // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
          'type'  :  (string),
          'id':  (string)
        },
    
        'ago' : (string),       // "x minutes ago" - currently English only
        'seen': (integer)       // null = unseen; (unix timestamp) = seen
        'clicked': (integer)    // null = unclicked; (unix timestamp) = clicked
    }
    ]
    

Misc 

Force to return raw result (content of “data”)

You can force the API to return the raw-result (content of “data”) by appending ?forceRaw=1 to the request.

JSONP-Fallback

Append ?callback=param to the request.

Pagination

Use offset=(integer) and limit=(integer) parameters.

Feeds 

Feeds 

Get a specific feed
/feeds/{type}

[LOGIN REQUIRED]

  • Parameters
  • type
    string (required) Example: home

    Receive the feed in form of a stomt-collection

    Choices: home discover

  • Request
  • Headers
    Content-Type: application/json
  • Response  200
  • Body
    A collection of stomts (see "stomts" for further information)
    
Search anything on stomt
/search/{?q}{&c}{&ll}
  • Parameters
  • q
    string (required) Example: iPhone

    Term to search for

    c
    string (optional) Default: all Example: all

    Search in a specific category

    Choices: all person hashtags

    ll
    string (optional) Example: 27.175015,78.042155

    Latitude,Longitude (may improve search result)

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "users": {
          // Each result has the following data
          name: "test",
          id: "a157bf31099d104a859668783",
          slug: (string)(web), // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
          uri: (string)(web),
          src: "4sq",   // important for content attribution
          desc: "",
    
          // Category specific data
          fullname: "test",
      }
      "hashtags": {}
      "venues": {}
    }
    

Authentification 

We have two different authentification flows.

Normal Credential flow
  1. Register a user via POST req. to /authentication/
  2. Get an access token via POST req. to /authentication/session
Facebook Connect flow
  1. Login and automatically register if not exist via POST to /authentication/session

User Management 

Registers a new user
/authentication/

Register a new user

  • Request
  • Headers
    Content-Type: application/json
    Body
        {
          "username": (string),
          "email": (string),
          "password": (string),
          "fullname": (string),
        }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "user": (userobject)
    }
    
Verify e-mail
/authentication/

Verify the users email address. The user gets a link with /verify/{id}/{verification_code}

  • Request
  • Headers
    Content-Type: application/json
    Body
        {
          "userid": (string),
          "verification_code": (string)
        }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "success": (boolean)
    }
    
Deletes a user
/authentication/

[LOGIN REQUIRED]

  • Request
  • Headers
    Content-Type: application/json
    Body
        {
          "id":       (string)   // Hashid of the user
          "password": (string)   // The user has to verify his password
        }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "valid" : (boolean)
    }
    

Session management 

Login
/authentication/session

Normal authentification with credentials or Facebook-Connect. For FB-Connect you need to sign-in client-side to receive an accesstoken from Facebook.

  • Request
  • Headers
    Content-Type: application/json
    Body
        {
          // For Normal
          "login_method":     "normal"
          "emailusername": (string),
          "password": (string)
    
          // For Facebook
          "login_method":     "facebook"
          "fb_access_token": (string),
          "fb_user_id": (string)
        }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      // After "normal" login method
      "emailusername": (string),
      "password": (string)
    
      // After "facebook" login method
      "accessToken": (string),
      "refreshToken": (string),
      "user": (userobject)
    }
    
Logs out a user
/authentication/session

[LOGIN REQUIRED]

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "valid" : (boolean)
    }
    

Refresh your access token 

Refresh access token after 419
/authentication/refresh/
  • Request
  • Headers
    Content-Type: application/json
    refreshtoken: (string)
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "accesstoken": (string),
      "refreshtoken": (string),
      "user": (userobject)
    }
    

Check if still logged in 

[LOGIN REQUIRED]

Is the users access token still valid
/authentication/check/
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "valid" : (boolean)
    }
    

Forgot password 

Sends the user an email to reset his password

Creates a password reset possibility
/authentication/forgotpassword/
  • Request
  • Headers
    Content-Type: application/json
    Body
        {
          "usernameoremail": (string)
        }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "valid" : (boolean)
    }
    

Reset password 

Resets the users password and responds with a new session

Resets the password
/authentication/resetpassword/
  • Request
  • Headers
    Content-Type: application/json
    Body
        {
          "resetcode": (string),
          "newpassword": (string)
        }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "accessToken" : (string),
      "refreshToken" : (string)
    }
    

Stomts 

stomt 

stomt-related resources

A single stomt object. The stomt resource is the central resource in the stomt API. It represents one paste - a single stomt.

Read 

Reads a single stomt
/stomt/{id}
  • Parameters
  • id
    string (required) Example: 7n5c62n75v2n6o5fn5

    hashid of a stomt

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        'id' : (string),
    
        'creator' : {
          'name':  (string),
          'id'  :  (string),
          'uri':   (string)(web),
          'photo': (string)
        },
    
        'text' : (string),
        'photo': (string),
        'negative': (boolean),
    
        'target' : {
            'name':   (string),
            'id'  :   (string),
            'uri':    (string)(web),
            'photo':  (string)
        },
    
        'created_at' : (string),
        'anonym'            : (boolean),
        'lang'              : (ISO 639-1),
        'amountAgreements'  : (integer),
        'amountComments'    : (integer)
    
        // Only exists if (dios-agreed
        'agreed': {
            'id': (string), // Hashed ID of the agreement
            'negative': (boolean)
        }
    }
    

Create 

Creates a stomt
/stomts

[LOGIN REQUIRED]

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
    "target_id" : 1,                  // Unique targets hash-id
    "negative" : (boolean),                   // 0 = "is great because", 1 = "would be better if"
    "text" : (string),                // The users text (maxlength: 100 chars)
    "anonym" : (boolean),
    "img" : (string)                  // Base64 encoded STRING
    }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        'id' : (string),
    
        'creator' : {
          'name':  (string),
          'id'  :  (string),
          'uri':   (string)(web),
          'photo': (string)
        },
    
        'text' : (string),
        'photo': (string),
        'negative': (boolean),
    
        'target' : {
            'name':   (string),
            'id'  :   (string),
            'uri':    (string)(web),
            'photo':  (string)
        },
    
        'created_at' : (string),
        'anonym'            : (boolean),
        'lang'              : (ISO 639-1),
        'amountAgreements'  : (integer),
        'amountComments'    : (integer)
    
        // Only exists if (dios-agreed
        'agreed': {
            'id': (string), // Hashed ID of the agreement
            'negative': (boolean)
        }
    }
    

Delete 

Deletes a single stomt
/stomts/{id}

[LOGIN REQUIRED]

  • Parameters
  • id
    string (required) Example: 7n5c62n75v2n6o5fn5

    hashid of a stomt

  • Response  200
  • Headers
    Content-Type: application/json
    Body
      {
        "success" : (boolean)
      }
    

Agreements 

agreement 

agreement-related resource

A single agreement object.

In case the user already agreed and wants to revoke his (dis-)agreement, we do not want you to update the negative-attribute of the existing agreement via PUT. Just DELETE the old (dis-)agreement and POST a new one.

Create 

Creates an agreement
/agreements/

[LOGIN REQUIRED]

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
    "negative": (boolean),            // 0 = agreement, 1 = disagreement
    "stomt_id": (hashid),     // The unique hashid of the stomt
    "anonym": (boolean),      // true, false
    }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
    "negative": (boolean),            // 0 = agreement, 1 = disagreement
    "stomt_id": (hashid),     // The unique hashid of the stomt
    "anonym": (boolean),      // true, false
    }
    

Delete 

Revokes an agreement
/agreements/{id}

[LOGIN REQUIRED]

  • Parameters
  • id
    string (required) Example: 7n5c62n75v2n6o5fn5

    hashid of an agreement

  • Response  200
  • Headers
    Content-Type: application/json
    Body
      {
        "success" : (boolean)
      }
    

Targets 

target 

Targets are the most important and complex resources. stomt is built to feedback anything, even friends and general things (e.g. I wish life had a pause button). Therefore nearly anything is saved as a Target and depending on its type additional type specific data.

Currently available target types:

  • user

User specific details

  'details': {
    'id': (string),           // Hashid
    'slug': (string)(web),    // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
    'name': (string),         // Name
    'description': (string),  // Max. 100 Chars
    'website': (string),
    'fullname': (string),
    'gender': (string),       // male | female
    'email': (string),
    'password': (string),     // only writeable, not readable
    'lang': (ISO 639-1)       // en/de
    'birth': {
        'day': (integer),
        'month': (integer),
        'year': (integer)
    }

    // Not editable!
    'influencestatus': {
        'actualInfluencePoints': (integer)        // Actual amount of influence points
        'actualInfluenceLevel': (integer)         // Actual influencelevel
        'nextLevel': (integer)                    // Next influencelevel (actualInfluenceLevel + 1)
        'nextLevelPoints': (integer)              // Amount needed to reach the next level
        'nextLevelPointsDifference': (integer)    // Amount of points missing to reach the next level
        'influenceLevelBarPercentage': (integer)  // Percentage of points where next Level is 100%
        'influenceLevelBarWidthPx': (integer)     // optional | requires influence-bar-length
                                                  // via ?influenceBarMaxWidth parameter (pixel)
    }
  }

User specific statistics:

    'stats': {
        'amountFollowers': (integer),
        'amountFollows': (integer),
        'amountStomts': (integer)
    }
  • venue

Venue specific details

  'details': {
    'description': (string),
    'address': (string),
    'city': (string),
    'country': (string),
    'tel': (string)
  }

Venue specific statistics:

    'stats': {
        'amountFollowers': (integer),
        'amountStomts': (integer)
    }

Embed data

To add the target specific details, append ?embed=details. This will include a pre-defined target-specific (see above) dataset into the result.

If you just want to add a specific detail just name it directly. E.g. you want to have the users e-mail address. Just append ?embed=email or ?embed=email,website Use punctuation to retrieve nested variables: ?embed=birth.year

Target 

Get a specific target
/target/{id}
  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      'id':           (hashid),
      'displayname' : (string),
      'slug':         (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
      'type':         (string),
      'photo':        (string),             // URI
      'details':      (object)              // optional | embed=details; target specific
    }
    

Target:Details 

Get a specific target
/target/{id}?embed={?var}

You’ll receive the standard-target and the type-specific data embed.

  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      'id':           (hashid),
      'displayname' : (string),
      'slug':         (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
      'type':         (string),
      'photo':        (string),             // URI
      'details':      (object)              // optional | embed=details; target specific
    }
    

Target:Details 

Change target-type specific data
/target/{id}/details

Simply send the complete target including its details.

  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

  • Request
  • Headers
    Content-Type: application/json
    Content-Type: application/json
    Body
    {
      'id':           (hashid),
      'displayname' : (string),
      'slug':         (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
      'type':         (string),
      'photo':        (string),             // URI
      'details':      (object)              // optional | embed=details; target specific
    }
    
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      'id':           (hashid),
      'displayname' : (string),
      'slug':         (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
      'type':         (string),
      'photo':        (string),             // URI
      'details':      (object)              // optional | embed=details; target specific
    }
    

Target:Stomts 

Get stomts related to a specific target
/targets/{id}/stomts/{type}/{secondType}
  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

    type
    string (required) Example: created

    What to show: received or created stomts?

    Choices: received created

    secondType
    string (optional) Example: positive

    All of type typeor just the negative or positive ones?

    Choices: positive negative

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      'id':           (hashid),
      'displayname' : (string),
      'slug':         (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
      'type':         (string),
      'photo':        (string),             // URI
      'details':      (object)              // optional | embed=details; target specific
    }
    

Target:Follows 

Get a collection of targets a specific target is following
/targets/{id}/follows
  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
      {
        'target_id': (hashid),
        'displayname': (string),
        'slug': (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
        'type': (string),
        'photo': (URL string),
        'influencelevel': (integer),
        'amIFollowing': (bool),       // Current user following? userid-header required
        'memberSince': (string)       // 234 years
      }
    ]
    

Target:Followers 

Read
/targets/{id}/followers
  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

  • Response  200
  • Body
    [
      {
        'target_id':      (hashid),
        'displayname':    (string),
        'slug':           (string)(web), // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
        'type':           (string),
        'photo':          (string),   // URL
        'influencelevel': (integer),  // Only users
        'amIFollowing':   (bool),     // Only users | Current user following? userid-header required
        'memberSince':    (string),   // Only users | 234 years
        'info':           (string),   // Only Non-users
        'amountFollower': (integer)
      }
    ]
    
Follow
/targets/{id}/followers

[LOGIN REQUIRED]

  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
    'target_id_followed': (string)  // The followed targets hashed id
    }
    
  • Response  200
  • Body
    [
      {
        'id': (hashid),
        'displayname': (string),
        'slug': (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
        'type': (string),
        'photo': (URL string),
        'influencelevel': (integer),
        'amIFollowing': (bool),       // Current user following? userid-header required
        'memberSince': (string)       // 234 years
      }
    ]
    
Unfollow
/targets/{id}/followers

[LOGIN REQUIRED]

  • Parameters
  • id
    string (required) Example: 622df9169fe84f1c81ff9d841

    The unique hashid of the target

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
    'target_id_followed': (string)  // The followed targets hashed id
    }
    
  • Response  200
  • Body
    [
      {
        'id': (hashid),
        'displayname': (string),
        'slug': (string)(web),        // URI-Version of the name. E.g. "Hans Peter" => "Hans-Peter"
        'type': (string),
        'photo': (URL string),
        'influencelevel': (integer),
        'amIFollowing': (bool),       // Current user following? userid-header required
        'memberSince': (string)       // 234 years
      }
    ]
    

Changelog 

  • 05.09.2014 #1

    • This is a test
    • This is a multiline test
    • and now another test
  • 04.09.2014 #1

    • API goes online.

Backend Install 

This is the installation guide for Windows. I assume Linux users to be clever enough to anticipate the following steps.

1. Install pre-requiries

Install a webserver and MySQL

Just use XAMPP

https://www.apachefriends.org/de/index.html

Install git

http://msysgit.github.io/

Install composer

https://getcomposer.org/

2. Setup database

Create a database called stomt_backend.

3. Setup virtual host

Add following to your Apache2 Config (C:/xampp/apache2/conf/extra/httpd-vhosts.conf)

<VirtualHost *:80>
    DocumentRoot "C:/xampp/htdocs/stomt/backend/public"
    ServerName rest.local.stomt.com
    ServerAlias rest.local.stomt.com
</VirtualHost>

Add following line to your hosts-file

Add: 127.0.0.1 rest.local.stomt.com To: C:/Windows/System32/drivers/etc/hosts.

Open it with an Editor in administrator-mode. Add line, save. You do not have to restart your computer. hosts-file changes take effect immediately.

4. Pull the code

Use the develop branch to develope and the master branch to test your client-application against. master is always the current working version.

git clone git@git.stomt.com:stomt/backend.git

5. Install backend dependencies

Go to the backend directory and composer install.

6. Install migrations

php artisan migrate

7. Last step

Restart the webserver and use the base data to test the backend.

Troubleshooting 

I get a same-origin policy error

Something in the backend is broken or the backend is down. Should not happen.

I get a 419 error

Use your refresh token.

The backend “doesn’t work” anymore

The master branch should always work. Sometimes the path structures for composers autoload function needs to be updated. Please try to do the following four steps:

  1. Go into the backends root directory
  2. Update composer by composer self-update
  3. Update all dependencies by composer update
  4. Update the autoloader again by composer dump-autoload to add custom libraries

Generated by aglio on 16 Sep 2014