ERROR! The markdown supplied could not be parsed correctly. Did you forget to surround a code snippet with "~~~~"?

# Graph API Generic Rules

Current version: 2.0
Archive: [Graph API Generic Rules v1.0]


Graph API can be RESTful

* explicit paths
* easily extendable
* less documentation

A graph API is consisted of:

* [Objects]
* Activities ( [Verbs] )
* [Aggregations] 



The Graph API is object-based, as calling initially a uniquely addressed object you can browse progressively all data that you have permissions to get: starting with a User object you MAY ask for objects, aggregations or activities that are connected with the user, and by querying these objects you MAY find every linked information. It is a matter of connections and permissions how deep it goes into the graph. Uploading to a Graph API is a typical HTTP POST message to the proper path where the aggregation or group of objects are listed.

For the purposes of OPENi platform, and to simplify the way we access information, it is allowed to ask only data for the currently authenticated user. That means that no social connections among users, generated by OPENi, are allowed in the platform. In order to describe the current owner of the Cloudlet, we are going to use the word "me", meaning the current user_id of the authenticated user: e.g. information for the currently user can be retrieved by calling API_PATH/me and his blog posts by API_PATH/me/articles. If it is needed to address specific cloud-based service, the specific account_id can be used, to retrieve objects and connections from this service and only: e.g. to get the statuses from a cloud-based service the path would be 
API_PATH/account_id/statuses/.


A set of properties has been recognized, to be reused by different objects. The reason to group properties under specific structures is to create a more concrete documentation and a better data modelling that allows the reusability of 

The complete list is available here [Set of Properties]



## Required queries

* Request that targets the OPENi user (joins every account):

In order to address a Cloudlet owner (i.e. OPENi user), her USER_ID must be called; to avoid complex queries, and keep the same design among multiple services, the word "me" is used instead of a USER_ID. 

<code>
API_PATH/users
API_PATH/[USER_ID]
API_PATH/[USER_ID]/objects
API_PATH/[USER_ID]/activities
</code>

e.g.

<code>
POST API_PATH/me
	user=[object]
POST API_PATH/me/accounts
	account=[object]
GET API_PATH/me/photos
GET API_PATH/me/likes
DELETE API_PATH/me/photos 
	ids={list}
</code>

* *Requests that target an account of the user (account specific):* 

The account refers to a specific service, e.g. Facebook Profile, Twitter account etc.

<code>
API_PATH/[ACCOUNT_ID]
API_PATH/[ACCOUNT_ID]/objects
API_PATH/[ACCOUNT_ID]/activities
</code>

e.g.

<code>
POST API_PATH/[ACCOUNT_ID]/photos
	photo=[object]
POST API_PATH/[ACCOUNT_ID]/albums
	album=[photo]
GET API_PATH/[ACCOUNT_ID]/photos
GET API_PATH/[ACCOUNT_ID]/likes
DELETE API_PATH/[ACCOUNT_ID]/photos 
	ids={list}
</code>

* *Object targeted (account specific):*

Every object that is stored centrally in the Cloudlet of the user, can be addressed with its ID uniquely. Then any connection or referred object can be addressed. 

<code>
API_PATH/[OBJECT_ID]
API_PATH/[OBJECT_ID]/objects
API_PATH/[OBJECT_ID]/activities
</code>

e.g.

<code>
POST API_PATH/[PHOTO_ID]/comments
	comment=‘text’
GET API_PATH/[PHOTO_ID]
GET API_PATH/[PHOTO_ID]/comments
DELETE API_PATH/[PHOTO_ID]
DELETE API_PATH/[PHOTO_ID]/comments
	ids={list}
</code>

* *Aggregation targeted (account specific):*

Every aggregation that is stored centrally in the Cloudlet, can be addressed with its ID uniquely. Then any connection or referred object can be addressed. 

<code>
API_PATH/[AGGREGATION_ID]
API_PATH/[AGGREGATION_ID]/objects
API_PATH/[AGGREGATION_ID]/activities
</code>

e.g.

<code>
POST API_PATH/[AGGREGATION_ID]/photos
	photo=[object]
POST API_PATH/me/albums
	album=[object]
GET API_PATH/[AGGREGATION_ID]/photos
GET API_PATH/[AGGREGATION_ID]/comments
DELETE API_PATH/[AGGREGATION_ID]/photos 
	ids={list}
</code>




## Targeting multiple services

* When making a call to a {user} object, either with a GET or a POST method, there MAY be a filtering with {ACCOUNT_ID}s. If there is no filter, the content is posted to OPENi only, but it is retrieved from all the available accounts during the GET method. Every object posted through OPENi APIs to external services must be stored as a reference in the Cloudlet, creating an OPENi object. Additionally, in case a local duplicate in Cloudlet must be stored, the boolean property "store_locally" must be given; by default no duplicate is stored in user's Cloudlet.

e.g.

<code>
POST API_PATH/me/photos
	photo=[object]
	account_ids={ACCOUNT_ID, ACCOUNT_ID}
        store_locally=TRUE
GET API_PATH/me/photos/?account_ids={ACCOUNT_ID, ACCOUNT_ID}
</code>

in order to know what account_id are available, previously a request should be sent:

<code>
GET API_PATH/me/accounts/
</code>



# Basic Properties of an Object

A basic object is consisted of the following properties:


|Property |Description|Type |
|--|--|--|
|id| The id of the object, as it is uniquely defined inside the OPENi platform. | string |
|object_type| The predefined name of the object, either by the platform or by the developer. e.g. "photo", "video" | string |
|service| The service where this object is located, e.g. "OPENi", "Facebook", "Flickr", "Foursquare"| string |
|url| The web resource of the referenced object, can be an html page or a media file, e.g. "http://www.facebook.com/username" |  string |
|[Set of Properties] #From | The owner of the specific object, if available (e.g. a user object has not such object) | object |
|[Set of Properties] #Time | A set of properties defining time (created, etc) of an Object | object |

e.g. for photo from facebook

<code>
{
        "data": [
            {
                "file": {
                    "description": "",
                    "format": "",
                    "icon": "https://fbstatic-a.akamaihd.net/rsrc.php/v2/yz/r/StEh3RhPvjk.gif",
                    "size": "",
                    "title": ""
                },
                "from": {
                    "id": "146230588595",
                    "name": "Six D.O.G.S",
                    "object_type": "",
                    "url": ""
                },
                "height": 480,
                "id": "10152244915673596",
                "location": {
                    "height": "",
                    "latitude": 37.977449239669,
                    "longitude": 23.726915939344
                },
                "object_type": "photo",
                "service": "facebook",
                "tags": [
                    {
                        "id": "1070460231",
                        "name": "Aviva Kraus",
                        "time": {
                            "created_time": "2014-07-17T20:19:20+0000",
                            "deleted_time": "",
                            "edited_time": ""
                        },
                        "x-location": 44.375,
                        "y-location": 66.383331298828
                    }
                ],
                "time": {
                    "created_time": "2014-07-17T11:51:57+0000",
                    "deleted_time": "",
                    "edited_time": "2014-07-17T20:19:20+0000"
                },
                "url": "https://www.facebook.com/146230588595/photos/a.10152244910038596.1073741890.146230588595/10152244915673596/?type=1",
                "width": 720
            }
        ],
        "meta": {
            "next": "Doesn't Exist",
            "previous": "Doesn't Exist",
            "total_count": 1
        }
    }
</code>


or if the requested object had several objects under an aggregation, a meta field is used:

|Property |Description|_. Type |
|--|--|--|
|next| A link for the next objects | url |
|previous| A link for the previous objects | url |
|total_count| The number for the returned objects | int |


e.g. for album from facebook

<code>
{
        "data": [
            {
                "file": {
                    "description": "",
                    "format": "",
                    "icon": "https://fbstatic-a.akamaihd.net/rsrc.php/v2/yz/r/StEh3RhPvjk.gif",
                    "size": "",
                    "title": ""
                },
                "from": {
                    "id": "675350314",
                    "name": "Romanos Tsouroplis",
                    "object_type": "",
                    "url": ""
                },
                "height": 540,
                "id": "10153663494310315",
                "location": {
                    "height": "",
                    "latitude": 38.740304158626,
                    "longitude": 22.337778097106
                },
                "object_type": "photo",
                "service": "facebook",
                "tags": [
                    {
                        "id": "675350314",
                        "name": "Romanos Tsouroplis",
                        "time": {
                            "created_time": "2014-01-03T01:08:28+0000",
                            "deleted_time": "",
                            "edited_time": ""
                        },
                        "x-location": 69.861111111111,
                        "y-location": 29.2
                    },
                    {
                        "id": "1245494543",
                        "name": "Kwnstantinos Giannopoulos",
                        "time": {
                            "created_time": "2014-01-03T01:08:27+0000",
                            "deleted_time": "",
                            "edited_time": ""
                        },
                        "x-location": 34.861111111111,
                        "y-location": 39.296296296296
                    }
                ],
                "time": {
                    "created_time": "2014-01-03T01:04:47+0000",
                    "deleted_time": "",
                    "edited_time": "2014-01-03T01:08:39+0000"
                },
                "url": "https://www.facebook.com/photo.php?fbid=10153663494310315&set=a.10151051293210315.769137.675350314&type=1",
                "width": 720
            },
            {
                "file": {
                    "description": "",
                    "format": "",
                    "icon": "https://fbstatic-a.akamaihd.net/rsrc.php/v2/yz/r/StEh3RhPvjk.gif",
                    "size": "",
                    "title": ""
                },
                "from": {
                    "id": "675350314",
                    "name": "Romanos Tsouroplis",
                    "object_type": "",
                    "url": ""
                },
                "height": 158,
                "id": "10153515993905315",
                "location": {
                    "height": "",
                    "latitude": 48.2080555556,
                    "longitude": 16.3580555556
                },
                "object_type": "photo",
                "service": "facebook",
                "tags": [],
                "time": {
                    "created_time": "2013-11-24T21:12:17+0000",
                    "deleted_time": "",
                    "edited_time": "2013-11-24T21:13:34+0000"
                },
                "url": "https://www.facebook.com/photo.php?fbid=10153515993905315&set=a.10151051293210315.769137.675350314&type=1",
                "width": 720
            }
        ],
        "meta": {
            "next": "Doesn't Exist",
            "previous": "Doesn't Exist",
            "total_count": 2
        }
    }
</code>




## Contextual Data and Activities over OPENi objects

Any additional contextual data over an OPENi object, with references on other services or not, refer to the hierarchical OPENi object, when calling *API_PATH/{OPENi_OBJECT_ID}/more*  (see [Context API] )



## Post Rules



## Questions