Api

General remarks

API of Zyre is based on REST ideas, with all elements uniquely identified by their URL address. The API utilizes the commonly used GET, POST, PUT and DELETE commands to access and modify data. Data is formatted in JSON.

Unless stated otherwise, our API follows the specs of the RESTful Transport Later.

When creating or updating the objects, all properties starting with the underscore will be ignored (you do not need to include them at all).

Authentications

Each API call must include an ID of the Application interacting with Zyre, and ID of a User, on behalf of whom application is making the call. The mechanism used for the authentication is the 2-legged OAuth.

Example

Simple Geo Storage offers a good example: https://simplegeo.com/docs/api-endpoints/simplegeo-storage.

First thoughts on layer-based API that SGStorage offers:

  • No way to query records except via layer name. This means we can only use 1 layer for all records, meaning we can't use layers for structure, which would have been nice. I'd like to use com.zyre.region.city.restaurant.toilet, com.zyre.region.roadblock, com.zyre.region.city, etc. But I want to see all records near to me, or at least all records at same level, e.g. in city, in region, etc.
  • Only query is by location (or equivalent), within layer. We need queries like by user, by date/time, ranking, etc.

Here's what I'd make as a general solution:

  • Records have any structure and any field can be used for querying, i.e. it's all fully indexed. Maybe exceptions on text fields. But even then, we know how to index/search on text.
  • Records have longitude/latitude, and all queries can add "closest N records to some specified location". We don't need anything more complex, like bounding boxes, etc.

I'm still not sure about catergories/layers, and how these should work. I've some feeling they should be localizable, i.e. categories as children of records, e.g. country A has some structure, country B has a different structure.

Server

Currently at:

http://ec2-46-51-130-226.eu-west-1.compute.amazonaws.com:4080/

Objects

Thing

Things are fundamental data structures in Zyre: they map to real-world objects, with names, coordinates and photos. Things are what your users will view, add and edit most of the time they interact with Zyre.

Some examples of Things are: Poland (country), ToruĊ„ (city), Nicolaus Copernicus statue (statue), Green Way (restaurant), Desperado (pub), even individual dishes and drinks like noodles or a tequila.

Things form a hierarchic structure. Every Thing (apart from root-level Things) is a children of another Thing. Thus, for example, each statue could be a child of a city, which will be a child of a country. This way we keep the information organized instead of relying of purely geo-spatial coordinates.

Structure

  • _id: string, unique id for the element
  • _version: string, uniquely identifies version of the document
  • parent_id: string, id of the parent Thing
  • name: string
  • location: 2-element array of floats, latitude and longtitude
  • description: string
  • type_id: id referencing the Type object
  • _created_by_id: id referencing the User who added the element
  • _created_via_app_id: id referencing the App used to create the element

Resource URLs

GET http://zyre.com/things/<id> — requests the Thing, uniquely identified by its id
GET http://zyre.com/things — requests a list of Things
POST http://zyre.com/things — creates a new Thing
PUT http://zyre.com/things/<id> — updates a Thing

Examples

{
  "_id": "47cc67093475061e3d95369d",
  "_version": "47cc67093475061e3d95369d",
  "parent_id": "47cc67093475061e3d95369d",
  "name": "Nicolaus Copernicus statue",
  "description": "The monument presents Copernicus in academic dress. His left hand holds an astrolabe, and his right index finger points to the heavens. This symbolizes Copernicus' connection with astronomy and celestial studies. The monument is surrounded by stone benches and an adjoining stone water well.
The pedestal bears a Latin inscription drawn up by Alexander von Humboldt: \"Nicolaus Copernicus Thorunensis, terrae motor, solis caelique stator\" (\"Nicolaus Copernicus of Thorun, mover of the earth, stopper of the sun and heavens\").",
  "location": [53.010278, 18.605],
  "type_id": "47cc67093475061e3d95369d",
  "_created_by_id": "47cc67093475061e3d95369d",
  "_created_via_app": "47cc67093475061e3d95369d"
}

Type

Things are not created chaotically. Not only Things form a hierarchical order, but each Thing is an instance of a Type.

Types also form a hierarchical tree. Example types can be: country, city, statue.

Types enforce the proper hierarchy of things. Therefore, if there is a type "city", and is has a child "statue", then all Things that are statues must be child of Things that are cities. In other words, hierarchy of Types define what possible children Things can have.

Structure

  • _id: string, unique id for the element
  • _version: string, uniquely identifies version of the document
  • parent_id: string, id of the parent Category
  • name: string
  • description: string
  • _created_by_id: id referencing the User who added the element

Resource URLs

GET http://zyre.com/types/<id> — requests a Type, uniquely identified by its id
GET http://zyre.com/types — requests a list of Types
POST http://zyre.com/types — creates a new Type
PUT http://zyre.com/types/<id> — updates a Type

Example

{
  "_id": "47cc67093475061e3d95369d",
  "_version": "47cc67093475061e3d95369d",
  "parent_id": "47cc67093475061e3d95369d",
  "name": "Statue",
  "description": "Statue in a city",
  "type_id": "47cc67093475061e3d95369d",
  "_created_by_id": "47cc67093475061e3d95369d",
}

…Work in progress…

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License