Looks like you've got JavaScript disabled in your browser - you'll get a better site experience if you enable JavaScript

The Proxima Data Service

Proxima » Documentation » Using Proxima » The Proxima Data Service

What is the Proxima Data Service?
(POST) Create a new Object
(PUT) Update an existing Object
(GET) Get data for an existing Object
(GET) Search a Collection for matching Objects
Searches - Valid Match Operators
Searches - Limit the Result Set with limit and pagebreak
Searches - Order the result set based on a key value
Searches - Grouping the result set by a key value
Searches - Example Result Set
(DELETE) Delete an existing Object

What is the Proxima Data Service?

The Proxima Data service provides an API endpoint to store "objects" created by users. You can:

- Create new Objects in "Collections"
- Update existing Objects with new key value pairs
- Get the data for individual Objects
- Search collections for matching objects using search parameters
- Delete existing Objects

It's easiest to think of the Proxima Data Service API as a web-connected Database where you can create, update, search and delete entries.
(POST) Create a new Object

To create a new Object send a POST request to the Data Service API:
```
POST http://yoursite.com/api/data/collection
```
Note how we have included our collection name in the URL - all data objects MUST belong to a collection. Collections cannot be created by users, but must be created by a Jamroom master admin (i.e. you) ahead of time in the Proxima Data -> Data Collections section in your Jamroom APC. Think of a collection like a database "table" - it allows you to group objects by common criteria. In our example we show the name of the collection as "collection", but it will be named whatever you want it to be.

A collection can be set with specific permissions when it is created:

- Owner read and write - this is the default - when a user creates a new Object in the collection, only the User that created the object can READ, UPDATE or DELETE it - basically it is a "private" entry in the DB.

- Global Read Only - when a new Object is created, only the Owner will be able to UPDATE or DELETE it, but everyone else will be able to READ it.

- Global Read and Write - this basically "opens" the permissions - anyone can create, update or delete any object (so be careful!).

If your POST request is successful, you will receive a 201 Created response that looks something like this:
```
{
  code: 201,
  text: 'Created',
  note: 'item created',
  data: 
  {
    _id: 196,
    location: 'http://yoursite.com/api/data/collection/196'
  }
}
```
Just like when we created a new user account, you will get a unique "_id" in the response and "location" that you can then use at a later point to access or update the data stored in the Object.
Think of collections like you would tables in a database - a logical way to group items that share a common trait
You can also set a collection to be Read Only - this lets you create collections that can only be updated (or written to) by a client using the Master Key
(PUT) Update an existing Object

Once an Object has been created, it will have a unique "id" that can then be used at a later point to add (or remove) key/value pairs from it's data - i.e.:
```
PUT http://yoursite.com/api/data/collection/196?new_key=5
```
This would update the object with _id 196 and add a new key called "new_key" with a value of "5". You can create, update and delete keys all in the same call - i.e.
```
PUT http://yoursite.com/api/data/collection/196?new_key=50&old_key=__delete_key
```
would change the "new_key" value to "50" DELETE the "old_key" key completely (using what is called a "Value Function" - more on those below).
(GET) Get data for an existing Object

After a Data Object has been created, a GET request can be sent to the Object's unique URL to get the stored information about the Object - i.e.
```
GET http://yoursite.com/api/data/collection/196
```
As long as the requesting User account has access to the item (i.e. they created it, or the user has "read" ability based on the collection permissions, or the user_id has been specifically granted access to the item) then they will get a "200 OK" response with the data set containing the key value pairs that belong to the item:
```
{
  code: 200,
  text: 'OK',
  data: 
  {
    '10': 'integer key',
     _created: 1411160690,
     _updated: 1411160690,
     string: 'value',
     del_key: 'delete me',
     string2: 'value2',
     int_value: 10,
     int_value2: 20,
     int_value3: 30,
     decrement_key: 10,
     increment_key: 1
  }
}
```
(GET) Search a Collection for matching Objects

The Proxima Data service provides an extensive amount of options when it comes to searching collections for matching objects.

Searching a collection is done by sending a GET request to the "search" endpoint of a collection - i.e.:
```
GET http://yoursite.com/api/data/collection/search
```
The search endpoint allows you to:

- Find objects with specific keys that match search conditions
- Order a result set based on the value of a key
- Paginate and limit the result set to a specific number of objects

The search parameters that you pass into the search endpoint must be URL encoded - i.e.
```
GET http://yoursite.com/api/data/collection/search?search1=title%20eq%20example
```
This query adds a single search condition - "search1" - set to:

title eq example

All searches must be in the following format:

KEY OPERATOR VALUE

Where:

KEY - this is the key you want to search (i.e. "title", "name")

OPERATOR - this is the match operator you want to run on the key/value - i.e. "eq" is "equals" (see table below for all operators)

VALUE - this is the value that you want to match (or not match)

You can have multiple search conditions - just increment the search "number" in the parameter - i.e.

search1=
search2=
search3=
... etc.

Just note that the more search conditions you add, so the slower the query will run - especially once you have hundreds of thousands or millions of items in your collection.
Searches - Valid Match Operators

The follow match operators are valid for searches:

eq - (equals) is used to find objects with a key that matches your value exactly

neq - (not equals) is used to find objects with a key that does NOT match your value exactly

gt - (greater than) is used to find objects with a key that has a value greater than the provided value.

gte - (greater than or equal to) is used to find objects with a key that has a value greater than or equal to the provided value.

lt - (less than) is used to find objects with a key that has a value less than the provided value.

lte - (less than or equal to) is used to find objects with a key that has a value less than or equal to the provided value.

like - like is used to match a substring of a value with wildcards - i.e. "title like %testing%" would find all objects with a "title" key that contain the word "testing"

not_like - not_like is used to match a substring of a value with wildcards - i.e. "title not_like %testing%" would find all objects with a "title" key that DOES NOT contain the word "testing"

in - find objects that match a value in a set - i.e. "title in test,testing" would find objects with a title key that is equal to "test" or "testing"

not_in - find objects that do NOT match a value in a set - i.e. "title not_in test,testing" would find objects with a title key that is NOT equal to "test" or "testing"
Searches - Limit the Result Set with limit and pagebreak

You can limit the result set to a specific amount by using either the "limit" or "pagebreak" parameter.

LIMIT

Limit is used to limit the result set to the specified number of objects. Note that there is a "hard cap" of 100 as the maximum limit value. Default is "10" if no limit is provided.
```
GET http://yoursite.com/api/data/collection/search?search1=title%20eq%20example&limit=25
```
The above search would be limited to 25 results.

PAGEBREAK

Pagebreak is used for "paginating" a result set, and is used in conjunction with the "page" parameter to request a specific page in a result set:
```
GET http://yoursite.com/api/data/collection/search?search1=title%20eq%20example&pagebreak=10&page=5
```
The above would return a result set of 10 objects, from page 5 (records 41 -> 50). Like "limit", "pagebreak" has a max value of 100, and if no "page" parameter is provided, the default for "page" is "1".
Searches - Order the result set based on a key value

Using the "order_by" parameter you can specify the key value you would like a result set to be ordered by:
```
GET http://yoursite.com/api/data/collection/search?search1=title%20eq%20example&order_by=_created%20desc
```
The above query would find matching objects where the "title" key is set to "example", and the order the results by the time the object was created (descending).

So you can use any key in the object to order by, and the following order "Directions":

asc - Ascending - order the result set based on the key value from LOWEST to HIGHEST lexicographically (or if the key value is text, alphabetical A - Z)

desc - Descending - order the result set based on the key value from HIGHEST to LOWEST lexicographically (or if the key value is text, alphabetical A - Z)

numerical_asc - Numerical Ascending - order the result set based on the key value from LOWEST to HIGHEST numerically (i.e. 10 would come after 9 - NOT after 1) - use for keys with numerical values only.

numerical_desc - Numerical Descending - order the result set based on the key value from HIGHEST to LOWEST numerically (i.e. 1 would come after 2 - NOT after 10) - use for keys with numerical values only.

random - order the result set randomly.
Searches - Grouping the result set by a key value

You can limit the result set to only ONE object per a matching key value by using the group_by parameter:
```
GET http://yoursite.com/api/data/collection/search?group_by=category&order_by=category%20asc&limit=100
```
This query would return a SINGLE object for each unique "category" key value, limit the result set to 100 objects (each with a unique category), and order the result set alphabetically.

Searches - Example Result Set

{ code: 200,
  text: 'OK',
  data: 
  {
     _items: [
       { '10': 'integer key',
         _created: 1428169027,
         _updated: 1428169027,
         string: 'value',
         string2: 'value2',
         int_value: 10,
         int_value2: 20,
         int_value3: 30,
         update_key: 'update_value',
         decrement_key: 9,
         increment_key: 2 } 
     ],

     info: 
     { total_items: 1,
       total_pages: 1,
       next_page: 0,
       pagebreak: 3,
       page: 1,
       this_page: 1,
       prev_page: 0
     }
  }
}

Notes:

- The data object will contain an _items key that will be an array of objects - one object for each matching object in the result set

- The info key is an object that contains information about the result set including it's page values, total number of matched items and total number of pages

(DELETE) Delete an existing Object

An existing object can be deleted by sending a DELETE request to the Object's unique item URL - i.e.:
```
DELETE http://yoursite.com/api/data/collection/196
```
As long as the client making the request has WRITE access to the object, the object can be deleted. If successful, a "200 OK" response will be received:
```
{
  code: 200,
  text: 'OK'
}
```
Letting you know the item was successfully deleted.

The Proxima User Service

Using Proxima

The Proxima Bridge Service

The Proxima Data Service

Table of Contents:

What is the Proxima Data Service?

(POST) Create a new Object

(PUT) Update an existing Object

(GET) Get data for an existing Object

(GET) Search a Collection for matching Objects

Searches - Valid Match Operators

Searches - Limit the Result Set with limit and pagebreak

Searches - Order the result set based on a key value

Searches - Grouping the result set by a key value

Searches - Example Result Set

(DELETE) Delete an existing Object

Tags