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.
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.
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:
where returned fields are:
token_type - always bearer
expires_in – token operation time, 3600 seconds (1 hour)
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:
In the request heading: “Authorization: BEARER <access_token>”
where <access_token> - forwarded value (without quotations),
"Authorization: BEARER a03306150a"
within POST request parameter can be given as bearer_token или access_token.
bearer_token=a03306150a or access_token=a03306150a
GET request can be designed as bearer_token or access_token,
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, where you use the passcode looks like this:
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).
<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.
The unified access point access is open for non-authenticated users.
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 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:
__iexact – exact match, ignoring the difference between uppercase and lowercase text value letters; below is the list, where functions, that differ by a letter ‘i’ at the beginning of the name, are function variant without the preceding ‘i’, that ignores the difference between uppercase and lowercase letters;
__contains, __icontains – (text) field contains forwarded value
__in – field’s value is any value in the list, comma separated.
__gt, __lt, __gte, __lte – more, less, more or equal, less or equal
__startswith, __istartswith – the field begins with the forwarded value
__endswith, __iendswith – the field ends with forwarded value
__range – value field is within the range, stated in the initial and final values, forwarded comma separated (both border values are included in the range)
__year –value year for fields of the type data
__month – value month (1- January,12- December) for fields of the type data
__day – day of the month value (1-31) for fields of the type data
__week_day - weekday value (1- Sunday, 2- Monday,7- Saturday) for fields of the type data
__isnull – wether the field has value null (value is true or false); it’s important to distinguish empty values (for example empty line) from the value null.
__regex, __iregex – regular expression search.
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
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".
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!
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.
POST /api/v2/transport/vehicle_enterprise/171/?access_token=1234567890 HTTPS/1.1
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 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 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, appeared during the query execution are marked with the corresponding HTTPS protocol return codes.
404 NOT FOUND – an object is not available or not found; the transmitted URL makes reference to non-existent or unavailable to the user server object
401 UNAUTHORIZED – an operation, requested by the user for the given object is not available for him because of insufficient rights; at the same time, the other user may have enough rights to make the same operation using this very object; the given error may occur because of token aging.
500 INTERNAL SERVER ERROR – a server error; you are to abstain from making the request, that caused this error and address BaseRide developers to eliminate this error; when addressing the developers you are to give as much information about the error facts as possible: the request date and time, all the requests headers, browser, that made the request (if the request was made through the browser)
We recommended you to use the latest versions of jQuery, at least 1.7
Let’s suppose that we’ve already got the object obj by means of addressing the interface API:
The returned object has the following structure
options: [ ],
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:
Pay attention, that the request PATCH may not contain unchangeable fields.