API Reference

Elie Michel edited this page Jan 26, 2015 · 12 revisions

Evernest API

Overview

The API is available here : (http://evernest-api.azurewebsites.net](http://evernest-api.azurewebsites.net)

Authentication

Authentication system is working with keys. When a program asks something to the API, it must provide a key (usually in the http request's body) that will allow him to explain what it is and what it is allowed to do.

There are two kind of keys: user keys and source keys.

User keys

User keys allow the program that use it to act as if it was you. Such a key can do a lot of things, like create stream, sources, change rights… For obvious security reason, and because this case shouldn't happen really often, API doesn't allow a user key to delete anything, or to get or modify informations on your user. These actions can only be done on the website. You can easely create a new or delete a user key with the website.

Source keys

Source keys (or just keys) are really limited keys. They allow a program to authenticate itself as a source. Sources only have access to some streams, and can have a really limited access (see rights). You can create, modify, delete them with a user key, or directly via the website. You may want to read this part of the wiki to understand better the concept of source.

To use a key, you simply need to write it in your request. You can write it in the JSon request's body, or as a get parameter. For a source key, the parameter name is simply Key. For a user key, the parameter name is UserKey. Some API endpoints need a Key parameter while some others need a UserKey parameter. You can't use a user key as a key, or a key as a user key.

Data structures

Event

An event is only a little message (aka a string) contained by a stream.

Right

Rights are case-insensitive strings, that can have the following values:

right := None
      |  ReadOnly
      |  WriteOnly
      |  ReadWrite
      |  Admin
      |  Root

You can read or modify rights that your sources have on your streams if you're using a user key (see /Right).

Stream

A stream is represented by its id. It also has a name that shouldn't be used in your program for anything else than showing it it the user. It can contain a lot of events that you can pull and push (see /Stream) if the source you're using is allowed to do so.

Source

A source can be represented either by a key (when you use it to authenticate) or by its id. It also has a name that shouldn't be used in your program for anything else than showing it to the user. Source's id is unique for a user only. Source's id is usefull if you want to modify your source rights via a user key (see /Source).

User

From outside, a user is only and id and a name. It can be represented by its id or by one of its user keys. It has access to all its related streams and sources. You can have access to all these informations is you're using a user key (see /User).

Responses strucure

We are trying to use a coherent pattern for all API responses. API responses are always formatted as JSON.

Basically, there are two main cases: either your request is successfull, either it's not. You will have a boolean Success field at the root of your JSON body, like so:

{
  "Success": true|false,
  ...
}
Success

If the request succeeded, you'll find a "Response" field containing your response. The whole API Routes section will show the possible successfull responses.

Failure

If it doesn't, you'll have an "Error" field, containing at least a "Message" and an "HelpMessage" field, like so:

{
  "Success": false,
  "Error":
    {
      "Message": "ExampleError",
      "HelpMessage": "This is an example error."
    }
}

Some errors do add other fields. There is a list of errors you can get:

The BadArgument error happens when you gave an incorrect value for one (or many) argument(s). This error adds an Arguments field which is a list of bad arguments.

The BadRequest error happens when your request's body couldn't be parsed correctly, for some reason.

The MissingArgument error happens when a needed value was not given. This error adds an Arguments field which is a list of missing arguments.

The NotImplemented error happens when you're trying to use a function that isn't fully implemented. You should try later, or post an issue in this repository.

API Routes

Routes with a * star do need a user key.
Actions (GET and POST) are indicative, but the API should understand if you were using the other one.
The whole API is case-insensitive.

Short list

Routes with a * star do need a user key.

Here is for the right controller:

GET /Right/{StreamId}
* GET /Right/{SourceId}/{StreamId}
* POST /Right/{SourceId}/{StreamId}/Set/{Right}

Here is for the source controller:

GET /Source
* GET /Source/{SourceId}
* POST /Source/New

Here is for the stream controller:

GET /Stream/{StreamId}
GET /Stream/{StreamId}/Pull/{EventId}
GET /Stream/{StreamId}/Pull/{FromEventId}/{ToEventId}
GET /Stream/{StreamId}/Pull/Random
POST /Stream/{StreamId}/Push

Here is for the user controller:

* GET /User
GET /User/{UserId}

The following sections give some details on the routes that were listed here, and some example return values.

GET /Right/{StreamId}

Get the rights that your key has on the given stream. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "Right": "ReadOnly"
    }
}
* GET /Right/{SourceId}/{StreamId}

Get the rights the the source has on the stream. You must provide a user key. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "Right": "ReadWrite"
    }
}
* POST /Right/{SourceId}/{StreamId}/Set/{Right}

Set the right of the given source on the given stream. You must provide a user key. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "Guid": 
    }
}
GET /Source

Get some informations on the source corresponding to the given key. You need to provide a key in field Key. You will get your source key, source name, your source id, some informations about the user, and a list of related streams, with their id and their right. Your Return value looks like:

{
  "Success": true,
  "Response":
    {
      "Source":
        {
          "Key": "SourceKey",
          "Name": "MyPerfectSource",
          "Id": 42,
          "User":
            {
              "Id": 1337
            },
          "Streams":
            [
              {
                "Id": 27,
                "Right": "NoRight"
              },
              {
                "Id": 78,
                "Right": "Admin"
              }
            ]
        }
    }
}
* GET /Source/{SourceId}

Same as GET /Source, but you must provide a user key, and your source id.

* POST /Source/New

Creates a new source. You need to give your user key and a source name in field SourceName. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "Guid": ...,
      "Source":
        {
          "Key": "",
          "Name": ""
        }
    }
}
GET /Stream/{StreamId}

Returns some data concerning the given stream. Need a key that has read access on this stream. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "Stream":
        {
          "Id": 123,
          "Name": "Example",
          "Count": 4,
          "LastEventId": 5678
       }
    }
}
GET /Stream/{StreamId}/Pull/{EventId}

Get the event. You must provide a key that has read access to the stream. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "Event":
        {
          ?
        }
    }
}
GET /Stream/{StreamId}/Pull/{FromEventId}/{ToEventId}

Get all events between FromEventId and ToEventId (inclusive ?). You need to provide a key that has read access to the stream. Return value looks like:

{
  "Succes": true,
  "Response":
    {
      "Events":
        [
          {
            ?
          }
        ]
    }
}
GET /Stream/{StreamId}/Pull/Random

Same as /Stream/{StreamId}/Pull/{EventId}, except that you don't choose EventId.

POST /Stream/{StreamId}/Push

Push a new event. You need to provide a key that has write access to the stream. You must provide a Message field in your body containing the new event's message. Return value looks like:

?
* GET /User

Get informations on the user represented by the user key that you must provide. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "User":
        {
          "Id": ,
          "Name": "",
          "Sources":
            [
              {
                "Id": 
              },
              {
                "Id": 
              }
            ],
          "Streams":
            [
              {
                "Id": 
              },
              {
                "Id":
              }
            ]
        }
    }
}
GET /User/{UserId}

Get informations on the user represented by its id. Return value looks like:

{
  "Success": true,
  "Response":
    {
      "User":
        {
          "Id": ,
          "Name": ""
        }
    }
}
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.