By means of the given API, systems and applications developers may collaborate with BaseRide to get and update any information, available for the user, associated with the developer’s app.

 

Programmer's Guide

 

External apps support

BaseRide supports external apps connection via HTTPS API. External apps have the same access privileges to the data as the user, registered in BaseRide. For authentication of the external app user we are to go through the authentication procedure OAuth2. Для аутентификации пользователя внешнего приложения используется процедура аутентификации OAuth2.

 

External apps registration

External app should be registered in BaseRide. External apps registration is available for all users, related to the group external_developer.

List of user external apps is available only to the user personally.

To register the app you are to open the list of external apps and add information about the external app there. The external app will get the app’s unique key and the app’s passcode.

External app should have a special redirection URL, where information about authorization time code on the BaseRide server will be sent.

The user can add, edit and delete records considering external apps.

 

Authentication procedure

For external app user authentication, this app should suggest the user to pass in the browser to a specific URL like https://baseride.com/oauth2/authorize/?response_type=code&client_id=<client_id>,

where <client_id> is the unique app’s key, assigned during the app’s registration.

The access to this URL should be authenticated by BaseRide user or in a common way when the user enters the username and password using the authentication mode (to which the user will be redirected out of the browser, if he is still not authenticated), or according to the basic authentication protocol (Basic Authentication).

To authenticate the user according to the basic authentication protocol, the request should contain the following request header:

   

Authorization: Basic XxXxXxXx==

Where XxXxXxXx== - is the encoded by means of Base64 line username:password, where username – is BaseRide username and a password – is BaseRide user password.

   

When authentication is successfully passed, BaseRide server will redirect you to the user browser by the redirection URL, indicated during the app’s registration, adding the parameter code=<code> to the redirection URL, where code=<code>, - is a temporary authorization code on the BaseRide server.

The temporary authorization code functions during 2 minutes as sent from the BaseRide server to redirection URL of the external app. The external app’s client can remove the temporary authorization code right out of the heading location, analyzing the result of the specific URL request.

The external app’s server can remove the temporary authorization code at addressing to its redirection URL.

The temporary authorization code may be used only to get access token.

 

Getting the access token

To get the access token to the BaseRide server the external app runs a query to get the token as https://baseride.com/oauth2/token/?callback=<callback>&client_id=<client_id>&client_secret=<client_secret>&code=<code>&grant_type=authorization_code&redirect_uri=<redirect_uri>,

 

where <callback> - arbitrary callback name to answer the request JSONP,

<client_id> - the unique app’s key,

<client_secret> - the app’s passcode,

<code> - just obtained authorization temporary code,

and <redirect_uri> should coincide with the redirection URL, specified during the app’s registration.

 

The request parameters can be forwarded in request parameters GET or request POST. Query answer is the JSON data or JSONP (depending on the fact whether the parameter callback was specified or not) as:

{

    access_token: "a03306150a",

    token_type: "bearer",

    expires_in: 3600,

    refresh_token: "c4cdaa0565",

    scope: ""

    }

where returned fields are:

 

access_token

token_type - always bearer

expires_in – token operation time, 3600 seconds (1 hour)

refresh_token

scope – token scope, not used at the moment

 

Instead of forwarding <clent_secret> in the request parameters you may forward this value in the heading Authorization, using the scheme HTTPS authorization BASIC and the value Credentials as <client_id>:<client_secret>, as if <client_id> were the username and <client_secret> - the password.

 

Getting access to API

The access token level (access token slot) may be used by the external app to get the access to the user’s data. That’s why, when addressing the BaseRide API server, you are to indicate this value using one of the three ways:

 

"Authorization: BEARER a03306150a"

for example:

bearer_token=a03306150a or access_token=a03306150a

bearer_token=a03306150a или     access_token=a03306150a

 

Token operating time is indicated in the field expires_in and is equal to 1 hour (3600 seconds) Token scope (field scope) is not used at the moment.

 

Access token upgrade

Access token has the limited operation time, that’s why the app should be regularly upgraded. To upgrade the access token, refresh_token is used.

To upgrade access token, the external app makes a request to token upgrade URL.

The request can be made from both the app’s server (in this case app’s security pass can be used) and from the client’s part of the app or JavaScript on the user’s page (in this case to authorize the upgrade request just got out of date token is used, which authorizes only this request).

The request, where you use the passcode looks like this:

https://baseride.com/oauth2/token/?callback=<callback>&client_id=<client_id>&client_secret=<client_secret>&grant_type=refresh_token&refresh_token=<refresh_token>.

The request, where you use out of date access token looks like this: https://baseride.com/oauth2/token/?callback=<callback>&client_id=<client_id>&grant_type=refresh_token&refresh_token=<refresh_token>&access_token=<access_token> (имя параметра access_token может быть и bearer_token).

 

Request parameters:

<callback> -- arbitrary callback name to answer the request JSONP,

<client_id> - the unique app’s key,

<client_secret> - the app’s passcode,

<access_token> - access token that needs upgrade,

<refresh_token> - upgrade token, that you get earlier

 

The request form is similar to the getting token request, which we have already described.

 

When you make a request, the upgrade token which is already used and access token that you’ve got together with the upgrade token, stop to exist.

Access token upgrade is possible during 4 hours after its time out.

 

Using app’s unique key and security pass

The unique app’s key may be placed on app’s pages or in the app’s software code, its content is not confidential and may be passed on to the third party.

It’s possible, because along with the unique key, the app has the security pass.

The app’s security pass, on the contrary, should be known only to the app’s developer and the app’s server. You are to avoid the security pass setting on pages or software code of the client part of your app (for example, in a mobile app), visible for the app’s user, because in this case both the unique key and the security pass can be easily removed out of the page or the software code.

To avoid such attacks the app should make requests to get and upgrade access token, where the app’s security pass is used only from the app’s server-side, placing the obtained access token on the app’s page (and/or returning it in the query answers of the app’s clients’ part to your server).

 

Access point to API BaseRide

At the moment, the only API version is v2, therefore, unified access point to API looks like https://baseride.com/api/v2/

At API access you are to indicate the parameter format=<format>,

where <format> has a value json, xml, yaml or plist.

Formats’ description is beyond the contents of this document.

 

When you address the unified access point, API returns all the data providers, accessible via API: 

https://baseride.com/api/v2/?format=json.

The unified access point access is open for non-authenticated users.

 

Front-end URL

Each data provider has several interfaces (URL, whose prefix is the unified access point).

All the interfaces of one data provider are indicated in provider‘s description when addressing the unified access point.

Interface access is open only for authenticated users. Herein, the access right to the groups and separate data objects are regulated in accordance with the same rules as the access rights in the administrative part of the BaseRide user interface.

Each data interface has at least three interfaces: data list interface, separate data object interface and data scheme interface. Most data providers have text data search interface. Separate data providers have additional interfaces for access to the additional data structures, connected with the main interface object.

For example, data provider about the route variant https://baseride.com/routes/route_variant/ has additional interface, with the help of which you can get geometrical arrangement of route option together with the stops.

 

Receiving data

Receiving data is made by means of request GET to the data provider interfaces. The request should contain parameter format=<format>, where <format> has value json, xml, yaml or plist.

 

Objects’ list and per-page output

Data list and data search interfaces, and also some additional interfaces, that return data lists, can return data per-page.

If the interface supports per-page data return, the returned value contains two keys: meta and objects. The key objects contain objects list, and the key meta – per-page output parameters and references next and previous for the following and previous pages.

On default, 20 objects fit on the page. Size and location of the page in returned data list are regulated by request parameter limit and offset. To turn off limitation for a number of output objects, you can indicate parameter limit=0.

 

Objects text search

Objects’ text search is made as a rule by means of prefix of all text and integer-valued object fields. To fulfill the search, you are to address search interface, forwarding the parameter q, containing search value, space-separated.

 

Objects’ detailed search

This sort of filtration is made according to the restrictions, imposed both on object fields and on the fields of the connected with it objects.

You can get objects fields list by means of data scheme interface, that all data providers have.

Fields and values are filtration conditions, forwarded as request parameters. All the forwarded filtration conditions are aggregated by cumulative operator “And”.

Thus, the list contains only those objects, for which all the forwarded conditions were fulfilled.

 

Then if you need to restrict the list with objects, containing definite field value, the parameter looks like <field’s name>__exact=<value>, where <value> is not placed in inverted commas. Suffix __exact is optional.

Besides the exact match, you can indicate other filtration functions for filtration. Filtration function is forwarded by means of suffix, beginning with two underline characters.

 

Filtration functions list:

 

 

You must carefully use functions __contains, __endswith and __regex for the search, as the can greatly slow request execution.

For filtration you may use not only object’s fields, but also fields of the objects, connected with this object. For connected objects’ fields reference, fields names, that make up a way till the interest value, should be connected by means of double underline.

For example, to find route variants, whose rout’s name coincides with the line ‘т17’, when addressing route variants list, you are to create parameter route__name__exact=т17

 

Getting information content of a separate object

Addressing the separate data object interface returns detailed content of the requested object.

 

 

Data modification requests

Optional headers and parameters

 

Request type

To make data modifications, requests of the type POST, PATCH and DELETE are made.

BaseRide server supports only requests of the type GET and POST. Other request types should be forwarded in the additional header of request X-HTTPS-Method-Override, for example "X-HTTPS-Method-Override: PATCH".

 

Data types

On BaseRide server data is forwarded as a telerequest. To recognize the format of the transmitted data you are to indicate it in the request header Content-Type, in a form “application/<format>” (for example "Content-Type: application/json").

All the formats enumerated for request parameter format are supported.

Data transmission in format x-www-form-urlencoded is not supported!

 

Access token

At making request, authentication and authorization are made according to the access token.

The access token can be forwarded in the URI request as a parameter, while the request data will be transmitted as telerequest in a format, indicated in the request header Content-Type.   

 

For example:

POST /api/v2/transport/vehicle_enterprise/171/?access_token=1234567890 HTTPS/1.1

Content-Type: application/json

X-HTTPS-Method-Override: PATCH

{“name”:”MyEnterprise”}

   

 

Adding an object

Add an object by means of request POST, addressed to the object list interface of the data provider.

Information content of the request body POST should be a structure, similar to the interface return value of the separate data object of the same data provider.

To exclude authentication cross-cut of newly made objects, you are to abstain from definite object identifier transmission when creating a new object. In this case, newly created object identifier will be made automatically.

If the new object is successfully created you’ll get a return code 201 CREATED, and the request answer will contain the header Location.

 

For example: “Location: https://BaseRide.doroga.tv/api/v2/transport/vehicle_park/8/” with the reference to a newly created object

 

Object modification

Object modification is made by means of request PATCH, addressed to the interface of separate data object.

The request body is a structure, similar to the returned interface value of the separate data object of the same data provider.

The structure should contain fields, which values are to be changed.

Object, subjected to modifications is identified according to the forwarded URL.

Successful object modification is marked by a return code 202 ACCEPTED.

 

Object deletion

Object deletion is made by means of request DELETE, addressed to data of a separate object interface. The object, subjected to deletion, is identified according to the forwarded URL.

Successful object deletion is marked by a return code 204 NO CONTENT

 

Errors codes

Errors, appeared during the query execution are marked with the corresponding HTTPS protocol return codes.

 

Parameters and code example at javascript/jQuery.ajax for data modification

We recommended you to use the latest versions of jQuery, at least 1.7

You may get your version by addressing the JavaScript control console on the page with the downloaded jQuery with the help of the following syntax:

 

$().jquery

   

Let’s suppose that we’ve already got the object obj by means of addressing the interface API:

 

$.ajax("https://cloud.doroga.tv/api/v2/transport/vehicle_enterprise/16/?format=json&access_token=1234567890",{

    success:function(obj) {

    ...

    }

    });

 

    The returned object has the following structure

    {

    description: "",

    id: 16,

    name: "demo",

    options: [ ],

    parks: [

    "/api/v2/transport/vehicle_park/13/"

    ],

    resource_uri: "/api/v2/transport/vehicle_enterprise/16/",

    routes: [

    {

    route: "/api/v2/routes/route/55/"

    },

    {

    route: "/api/v2/routes/route/124/"

    },

    {

    route: "/api/v2/routes/route/167/"

    }

    ]

    }

 

Now we want to add object description “Display” and change the routs list, removing the route with the identifier 167. To do this, we make the request PATCH, using the following code:

 

$.ajax("https://cloud.doroga.tv/api/v2/transport/vehicle_enterprise/16/?format=json&access_token=1234567890",{

    type:"POST",

    data:JSON.stringify({

    description: "Display",

    routes: [

    {

    route: "/api/v2/routes/route/55/"

    },

    {

    route: "/api/v2/routes/route/124/"

    }

    ]

    }),

    processData:false,

    contentType:'application/json',

    headers:{'X-HTTPS-Method-Override':'PATCH'},

    success:function(obj) {

    console.log('SUCCESS:',obj);

    },

    error:function(obj) {

    console.log('ERROR:',obj);

    }

    }); 

 

 

Pay attention, that the request PATCH may not contain unchangeable fields.