Skip to content

API Reference

victorjonsson edited this page · 35 revisions

In this document we will go through the API operations that is available in PHP-Rocker out of the box. All these operations is declared in config.php. You can add and remove operations as you want (here you can read more about how to create your own operations)

The content-type returned by the server is by default json, which is configureable in config.php. You can however always add the extension .xml to the end of the URI to get a XML-formatted response instead.

These examples uses curl but a PHP-client is also shipped with PHP-Rocker. You can also use rocker.js, a javascript client that works both as a node module and as an ordinary web script.

User management

File storage

System

Here you can read more about how to create your own API operations

User management

Create user

The parameters email, nick and password is mandatory. The meta parameter must be an associative array. Setting a meta value to true or false will turn the value into corresponding boolean value.

$ curl -X POST https://website.com/api/user -d 'email=some.user@website.com&nick=Nicky&password=secretstuff&meta[country]=Germany'

HTTP/1.1 201 Created
Date: Tue, 12 Mar 2013 06:27:44 GMT
...

{
    "id" : 3,
    "email" : "some.user@website.com",
    "nick" : "Nicky",
    "meta" : {
        "country" : "Germany"
    }
}

The API will respond with status 409 if trying create a user with an e-mail that already exists in the database.

Update user

Any of the parameters email, nick, password and meta can be given. The meta parameter must be an associative array. Setting a meta value to null will remove the meta value. Setting a meta value to true or false will turn the value into corresponding boolean value. To update a user the client has to authenticate as the user in question or as a user that has admin privileges.

$ curl -X POST https://website.com/api/user/some.user@website.com -d 'nick=Johnny&meta[country]=Norway&meta[adult]=true'

{
    "id" : 3,
    "email" : "some.user@website.com",
    "nick" : "Johnny",
    "meta" : {
        "country" : "Norway",
        "adult" : true
    }
}

Delete user

To delete a user the client has to authenticate as the user in question or as a user that has admin privileges. To remove a user that has admin privileges you first have to remove the admin privileges.

$ curl -X DELETE https://website.com/api/user/some.user@website.com 

HTTP/1.1 204 No Content
Date: Tue, 12 Mar 2013 06:18:59 GMT
...

Get user

You can request users by using the user ID or the e-mail of the user eg. https://website.com/api/user/10034 or https://website.com/api/user/john.doe@gmail.com

$ curl https://website.com/api/user/john.doe@gmail.com

{
    "id" : 1034,
    "email" : "john.doe@gmail.com",
    "nick" : "John",
    "meta" : {
        "country" : "Canada"
    }
}

Get user data belonging to the authenticated user

$ curl -u 'admin.user@website.com' https://website.com/api/me

{
    "id" : 1,
    "email" : "admin.user@website.com",
    "nick" : "Admin",
    "meta" : {
        "admin" : 1
    }
}

Granting admin privileges

The client has to authenticate as a user that has admin privileges to manage privileges for other users. An admin user can how ever not remove admin privileges from him self.

$ curl -X POST https://website.com/api/admin -d 'user=3&admin=1'

HTTP/1.1 204 No Content
Date: Tue, 12 Mar 2013 06:18:59 GMT
...

Search users

Query string examples (parameters needs to be url encoded):

Search for users that has a nick containing John and that comes from France

?q[nick]=*john*&q[country]=France

Search for users that has a nick containing John and that comes from either France or Norway

?q[nick]=*john*&q[country]=France|Norway

Search for users that has a nick containing John and that comes from either France or Norway and that has a hobby interest containing the word Hockey or Soccer

?q[nick]=*john*&q[country]=France|Norway&q[interests]=*hockey*|*soccer*

Search for users that has a name containing John and that doesn't go at the school "Haga" and that has an average grade above 18

?q[nick]=*john*&q[school!]=Haga&q[grade>]=18

You can also add the parameters offset and limit

$ curl https://website.com/api/user?q[nick]=*john*&q[country]=France|Norway&q[admin!]=1&offset=50&limit=100

{
    "matching" : 234,
    "objects" : [
        {...},
        ...
    ]
}

List users

The parameter q can also be used to list users. The property matching will in this case represent the total amount of users in the database.

$ curl https://website.com/api/user?q=all&offset=0&limit=100

{
    "matching" : 3023,
    "objects" : [
        {...},
        ...
    ]
}

File storage

If you don't want to store files on the server you can setup PHP-Rocker to use Amazone S3 instead, read more here

Put file

Files stored on the server will be mapped against the authenticated user. The file data returned when calling this operation successfully will also be present when requesting user data.

You can also tell the server to base64 decode the content that you've sent in the request body by adding request parameter base64_decode=1

$ curl -u admin@website.com -X PUT https://website.com/api/file/my-file.json -d '{"prop":"value"}'

HTTP/1.1 201 Content Created
Date: Tue, 12 Mar 2013 06:18:59 GMT
...

{
    "name" : "1034/my-file.json",
    "extension" : "json",
    "size" : 16,
    "location" : "http://website.com/static/1034/my-file.json"
}
$ curl -u admin@website.com https://website.com/api/me

{
    "id" : 1034,
    "nick" : "Johny",
    "email" : "admin@website.com"
    "meta" : {
      "files" : {
        "my-file.json" : {
          "name" : "1034/my-file.json",
          "extension" : "json",
          "size" : 16,
          "location" : "http://website.com/static/1034/my-file.json"
        }
      }
    }
}

The file properties width and height will also be present in the file data in case the created file was an image of type image/jpeg, image/gif or image/png.

Delete file

$ curl -u admin@website.com -X DELETE https://website.com/api/file/my-file.json

HTTP/1.1 204 No Content
Date: Tue, 12 Mar 2013 06:18:59 GMT
...

Image versions

When creating an image file you may also send an array in the query string, declaring which image versions you want the server to create, eg. ?versions[thumb]=100x100&versions[medium]=300x0. The dimensions of the image version is declared [width]x[height]. The image version will be cropped unless you set any of the dimension parameters to a zero value, in that case the image version will keep its original proportions.

$ curl -u admin@website.com -X PUT https://website.com/api/file/kittens.jpg?versions[thumb]=100x100&versions[medium]=300x0 -d '...'

HTTP/1.1 201 Content Created
Date: Tue, 12 Mar 2013 06:18:59 GMT
...

{
    "name" : "1091/kittens.jpg",
    "extension" : "jpg",
    "size" : 402400,
    "width" : 900,
    "height" : 900,
    "location" : "http://website.com/static/1091/kittens.jpg",
    "versions" : {
        "thumb" : "kittens-100x100.jpg",
        "medium" : "kittens-300x0.jpg"
    }
}

Generating new image versions

To generate new image versions you simply POST the version data to the file resource

$ curl -u admin@website.com -X POST https://website.com/api/file/kittens.jpg -d 'versions[large]=600x600'

{
    "name" : "1091/kittens.jpg",
    "extension" : "jpg",
    "size" : 402400,
    "width" : 900,
    "height" : 900,
    "location" : "http://website.com/static/1091/kittens.jpg",
    "versions" : {
        "thumb" : "kittens-100x100.jpg",
        "medium" : "kittens-300x0.jpg",
        "large" : "kittens-600x600.jpg"
    }
}

Removing image versions

To remove image versions you do the same as when you create them except that you use request method DELETE.

$ curl -u admin@website.com -X DELETE https://website.com/api/file/kittens.jpg -d 'versions[]=large&versions[]=medium'

{
    "name" : "1091/kittens.jpg",
    "extension" : "jpg",
    "size" : 402400,
    "width" : 900,
    "height" : 900,
    "location" : "http://website.com/static/1091/kittens.jpg",
    "versions" : {
        "thumb" : "kittens-100x100.jpg"
    }
}

System

Get version of Rocker

$ curl http://website.com/api/system/version

{
    "version" : "0.9.1"
}

List available operations

$ curl http://website.com/api/system/operations

{
    "operations" : {
        "methods":"GET,HEAD",
        "class":"\\Rocker\\API\\ListOperations"
    },
    "system/version" : {
        "methods":"GET,HEAD",
        "class" : "\\Rocker\\API\\Version"
    }
    ...
}

Clear object cache

Clear object cache on remote server

$ curl -u 'admin.user@website.com' -X POST http://website.com/api/system/cache/clear

HTTP/1.1 204 No Content
Date: Tue, 12 Mar 2013 06:18:59 GMT
...
Something went wrong with that request. Please try again.