Direct API

Introduction

In this guide you will find basic information about the principles of Ocugine Direct API and about preparing for its use. If you have already worked with our API or with similar services from other platforms, and know which application you want to create, we recommend that you go to the appropriate section of the documentation.

API (application programming interface) is an intermediary between the application developer and any environment with which this application should interact. The API makes it easy to create code because it provides a set of ready-made classes, functions, or structures for working with existing data.

1. Methods and Objects

Ocugine Direct API — it is an interface that allows you to receive information from the Ocugine database and interact with all services via https requests to a special server. You do not need to know in detail how the database is organized, from which tables and fields of what types it consists of - it is enough that the API query “knows” about this. Query syntax and the type of data returned by them are strictly defined on the side of the service itself.

For example, to get data on the status of the API, you need to run the following query:

https://cp.ocugine.pro/api/state/

Consider separately all of its components:

  • https:// — connection protocol. The Ocugine API works only with a secure connection.
  • cp.ocugine.pro/api/ — API service address You will fulfill all requests through this interface.
  • state/ — name of the Ocugine API method. Methods are conditional commands that correspond to a particular operation with a database or service — information retrieval, recording, or deletion. For example, /auth/login/ - a method for authorization in the Ocugine control panel and further work with its services, and /auth/register/ - a method for registration in the Ocugine control panel.

All methods are divided into sections. For example, for working with users, this is users, for working with BaaS - backend, and so on. Note that the Ocugine API only works with POST requests and accepts data from POST headers.

In response, the server returns a JSON object with the requested data (or an error message if something went wrong). JSON is a format for writing data in the form of “property name”: “value” pairs.

The answer to our query looks like this:

{"complete":true,"message":null,"data":{"version":"0.4.0a","build":401,"developer":"CodeBits Interactive","url":"https://cp.ocugine.pro/","online":true}}

The answer will always contain 3 parameters:

  • complete (bool) - if false, it means an error has occurred. Or if true - it means the request was a success.
  • message (string) - error message. If there was no error at the time of the request, it returns null.
  • data (object) - an object with the data that the server returns to your request. If an error occurs during the request, null is returned.

The structure of the response of each method is also strictly defined, and when working with the API, you know in advance that a number will come in the build field, and a string in the version field. Such rules are negotiated on the pages with a description of the method and the corresponding objects, which it returns in the answer.

The object from the response may not be unique to a particular method.

2. Application Registration

In our example, the method /state/ was used, to call which it is enough just to specify its input parameters. But more often this will not be enough. You need to register your application to use all the features of the Ocugine Direct API.

How to create your first project (read this article).

After creating your project, you will be taken to the Ocugine Control Panel. Open the “Project Settings” tab in the menu on the left. You will see the "Application ID" field in which the number will be indicated, for example, 77814. This number is the application identifier, it is also APP_ID, CLIENT_ID, you will need it in your further work. In the same place you will find "Application Key" to work with your application. Typically, the "Application Key" is a string.

Under no circumstances should you pass the parameters of your application to third parties.

3. Authentication

In order to work with requests to the API, you need to get user authorization. As a rule, each SDK defines its own authorization method, but you can use the standard Direct API method.

To authorize a user and get access_token, you must execute a POST request to the following address:

https://cp.ocugine.pro/api/users/auth/

In the request, you must pass the following parameters:

  • login (string) - User Login
  • password (string) - User Password

The server will return you JSON-data in the following format:

  • is_auth (bool) - Authentication Status
  • login (string) - Login (or null if the user has logged in to the application for the first time)
  • access_token (string) - Token (or null if the user has logged in to the application for the first time)
  • access_url (string) - The URL to which the user should be redirected when you first use your application to verify rights.
  • profile_uid (double) - Profile UID
  • from (string) - Authentication Type

Registration and authorization through social networks is performed using the Ocugine SDK. You can find the list of SDKs on the "Plugins" page in the control panel.

4. Access Rules

As you have noticed, the first authorization in your application, the server gives you the access_url parameter. You must redirect the user to this URL in order to allow the use of the Ocugine account in your application.

If a user registers for the first time in Ocugine services through your application, or he has not previously installed other applications using Ocugine services, then you do not need to confirm access.

5. What's next?

You have learned the basic concepts associated with the Ocugine Direct API. Then everything depends on your inspiration.

Of course, in practice, no one works with the API from the next browser tab. To do this, use a variety of programming languages, SDK, code generators. The mechanism of working with the API is very simple, the means for sending https-requests and processing the response from the server are provided in almost any development environment: which means there is always a choice.

We also recommend to read: