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.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on May 13, 2024. It is now read-only.
Copy file name to clipboardExpand all lines: docs/core-concepts/api-calls-anatomy/index.md
+36-32Lines changed: 36 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,21 @@
1
1
---
2
-
title: API Calls Anatomy
3
-
hide_title: true
2
+
title: API calls' anatomy
3
+
hide_title: false
4
4
draft: false
5
-
sidebar_label: API Calls anatomy
5
+
sidebar_label: API calls' anatomy
6
6
sidebar_position: 1
7
7
tags:
8
8
- concept
9
+
- calls
10
+
- anatomy
9
11
keywords:
10
12
- trading
11
13
- concept
12
-
description: Deriv API calls Anatomy
14
+
- calls
15
+
- anatomy
16
+
description: Deriv API calls' anatomy
13
17
---
14
-
## Subscribe and Send
18
+
## Subscribe and send
15
19
16
20
All API calls have a send functionality for making a request and receiving a response. Certain API calls also offer a subscribe functionality allowing for updates to be sent to your application when new information becomes available.
17
21
@@ -23,42 +27,42 @@ Some of these API calls automatically subscribe (e.g. [ticks](https://api.deriv.
23
27
24
28
For example, you can call [Tick History](https://api.deriv.com/api-explorer#ticks_history) to receive tick history data. But when you add the `subscribe` option to this call, you will receive the tick history data you requested in the first response, and you will continue to receive a new response every time there is a new tick published by the server for the given symbol.
25
29
26
-
In the message stream from `subscribe` there is a field called `subscription`, this is the `Stream ID`. with this ID you can identify the message stream in your logic and stop the stream with `Forget` and `Forget All` API calls.
30
+
In the message stream from `subscribe`, there is a field called `subscription`. This is the `Stream ID`. With this ID, you can identify the message stream in your logic and stop the stream with `Forget` and `Forget All` API calls.
27
31
28
32
The data provided by API calls with the `subscribe` functionality can be used as a data source for other API calls and features.
29
33
30
34
### Send
31
35
32
-
If you call the API with the `send` functionality, then the server will only send back the requested data one time. In order to get updated data you have to send the API call again. Usually, this method is used when you get other API call responses or UI events such as `Click`, `Scroll` and more.
36
+
If you call the API with the `send` functionality, then the server will only send back the requested data one time. In order to get updated data, you have to send the API call again. Usually, this method is used when you get other API call responses or UI events such as `Click`, `Scroll`, and more.
33
37
34
38
### Forget
35
39
36
-
If you want to stop the message Stream created by `subscribe`, you will have to call the `Forget` API call with the correct `Stream ID`. Otherwise, you can use the `Forget All` API call to stop streams by their `Method name`.
40
+
If you want to stop the message stream created by `subscribe`, you will have to call the `Forget` API call with the correct `Stream ID`. Otherwise, you can use the `Forget All` API call to stop streams by their `Method name`.
37
41
38
42
:::caution
39
-
For more information on the `Forget` API call, you can have a look at [Forget](https://api.deriv.com/api-explorer#forget) and [Forget All](https://api.deriv.com/api-explorer#forget_all) in the API explorer.
43
+
For more information on the `Forget` API call, have a look at [Forget](https://api.deriv.com/api-explorer#forget) and [Forget All](https://api.deriv.com/api-explorer#forget_all) in the API explorer.
40
44
:::
41
45
42
46
43
-
## Request Data
47
+
## Request data
44
48
45
-
In order to make it easier for you to handle the `request` and `response` flow of your websocket connection, every deriv websocket API calls has a general structure. you can use it for caching, validation, request and response synchronization are some of the things you can use it for.
49
+
To make it easier for you to handle the request and response flow of your WebSocket connection, each Deriv WebSocket API call follows a standardised structure. You can use it for caching, validation, request, and response synchronisation.
46
50
47
-
#### API Call Method Name
51
+
#### API call method name
48
52
49
53
Every `request` in the WebSocket API includes a `method name` field that serves as a unique identifier for the request. In most cases, this `method name` will get a numerical value of `1`. However, there are some cases where the identifier property may have a string value.
50
54
51
55
:::caution
52
-
API Call Method Name is always required. this field determines the data you'll get from our websocket server.
56
+
API Call Method Name is always required. this field determines the data you'll get from our WebSocket server.
53
57
:::
54
58
55
-
### Required Fields
59
+
### Required fields
56
60
57
-
Every request data has several required fields which you must provide them and they may contain optional fields as well, let's explore this with an example on`Residence List`:
61
+
Each request data has mandatory fields that you must provide, and it may also include optional fields. Let's explore this with an example from`Residence List`.
58
62
59
-
`Residence List`Call returns a list of countries and 2-letter country codes, suitable for populating the account opening form.
63
+
A `Residence List`call returns a list of countries and 2-letter country codes, suitable for populating the account opening form.
60
64
61
-
Request data for this call is like so:
65
+
The request data for this call is as below:
62
66
63
67
```ts
64
68
{
@@ -68,27 +72,27 @@ Request data for this call is like so:
68
72
}
69
73
```
70
74
71
-
The `residence_list` field is the `method name` for the call and is required. There may be other required fields which are related to this type of the request you want to send. if you want to know more about `Residence List` and other API calls please check them out in the[API Explorer](https://api.deriv.com/api-explorer#residence_list).
75
+
The `residence_list` field is the `method name` for the call and is required. There may be other required fields related to this type of the request you want to send. To know more about `Residence List` and other API calls, please check them out in [API Explorer](https://api.deriv.com/api-explorer#residence_list).
72
76
73
-
### Optional Fields
77
+
### Optional fields
74
78
75
-
Every Call has several `Optional` fields as well, `passthrough` and `req_id` are always part of the request data but you can choose to opt-out and not use them.
79
+
Every call has several `Optional` fields as well. `Passthrough` and `req_id` are always part of the request data but you can choose to optout and not use them.
76
80
77
-
#### `passthrough`Field
81
+
#### The `passthrough`field
78
82
79
-
Whatever you pass to this field will be returned back to you inside a `response` object, this can be helpful when you need to simulate a stateful flow for your `requests` and `responses`.
83
+
Whatever you pass to this field will be returned back to you inside a `response` object. This can be helpful when you need to simulate a stateful flow for your `requests` and `responses`.
80
84
81
-
#### `req_id`Field
85
+
#### The `req_id`field
82
86
83
-
You may need to `tag` your requests and pass them through our `websocket` calls. you can do it by passing a `number` to this field. it can be helpful when you need to map `requests` to `responses`.
87
+
You may need to `tag` your requests and pass them through our `WebSocket` calls. You can do so by passing a `number` to this field. it can be helpful when you need to map `requests` to `responses`.
84
88
85
89
:::caution
86
-
There may be other optional fields for a request which are only related to that API call, please check our [API Explorer](https://api.deriv.com/api-explorer) to get familiar with them.
90
+
To learn about additional optional fields specific to each API call, please refer to our [API Explorer](https://api.deriv.com/api-explorer).
87
91
:::
88
92
89
-
## Response Data
93
+
## Response data
90
94
91
-
When you get the response for the call, there will be a `Field` with the same name as the `method name`. and it contains the actual data.
95
+
When you get the response for the call, there will be a `Field` with the same name as the `method name`, which contains the actual data.
92
96
93
97
The response for the `Residence List` call:
94
98
@@ -159,15 +163,15 @@ The response for the `Residence List` call:
159
163
};
160
164
```
161
165
162
-
Here the `residence_list` is the `method name` and it contains the actual data you requested. rest of the array is removed here for brevity sake, you can check the actual response [here](https://api.deriv.com/api-explorer#residence_list).
166
+
Here the `residence_list` is the `method name`, and it contains the actual data you requested. To keep it short, we haven't included the rest of the array. You can check the actual response [here](https://api.deriv.com/api-explorer#residence_list).
163
167
164
-
#### The `echo_req`Field
168
+
#### The `echo_req`field
165
169
166
170
This `Field` contains the exact `Request Data` you sent to the server.
167
171
168
-
#### The `msg_type`Field
172
+
#### The `msg_type`field
169
173
170
-
This `Field` helps you determine which `message` data you're getting on the message event of the websocket connection. For example, your `onmessage` event handler for your websocket connection in `Javascript` would be:
174
+
This `Field` helps you determine which `message` data you're getting on the message event of the WebSocket connection. For example, your `onmessage` event handler for your WebSocket connection in `JavaScript` would be:
Copy file name to clipboardExpand all lines: docs/core-concepts/authorization-authentication/index.md
+25-30Lines changed: 25 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,75 +1,74 @@
1
1
---
2
-
title: Authorization and Authentication
2
+
title: Authorisation and authentication
3
3
hide_title: false
4
4
draft: false
5
-
sidebar_label: Authorization and Authentication
5
+
sidebar_label: Authorisation and authentication
6
6
sidebar_position: 2
7
7
tags:
8
8
- authentication
9
-
- authorization
9
+
- authorisation
10
10
keywords:
11
11
- deriv-authentication
12
-
- deriv-authorization
13
-
description: deriv api authentication and authorization
12
+
- deriv-authorisation
13
+
description: Deriv API authorisation and authentication
14
14
---
15
-
16
-
Without authentication and authorization you'll only get access to roughly half of our API calls and features. for example in order to buy contracts or utilize the `Copy Trading` features your users must be authenticated and authorized by our **OAuth** provider and **Websocket Server**.
15
+
Without authorisation and authentication you'll only get access to roughly half of our API calls and features. For example, in order to buy contracts or utilise the `Copy Trading` features, your users must be authenticated and authorised by our **OAuth** provider and **WebSocket Server**.
17
16
18
17
## Before we start
19
18
20
-
You have to make sure you have all the requirements mentioned bellow to continue.
19
+
Please make sure you have all the requirements mentioned below to continue.
21
20
22
21
### Requirements
23
22
24
-
1. Deriv Account
25
-
2. Deriv API Token with the appropriate access level
26
-
3. Deriv App ID
23
+
1. Deriv account
24
+
2. Deriv API token with the appropriate access level
25
+
3. Deriv app ID
27
26
28
27
:::note
29
-
Please refer to [Setting up a Deriv Application](/docs/setting-up-a-deriv-application.md) for detailed instruction how to create Deriv API token and Applications
28
+
Please refer to [Setting up a Deriv application](docs/setting-up-a-deriv-application.md) for detailed instructions how to create a Deriv API token and application.
30
29
:::
31
30
32
-
### API Token
31
+
### API token
33
32
34
-
An API token is a unique identifier of a client that requests access from a server. It's the simplest way of authorization.
33
+
An API token is a unique identifier of a client that requests access from a server. It's the simplest way of authorisation.
35
34
36
35
The access level for each API token has to match the required access level of each API call, which can be found in the [API Explorer](https://api.deriv.com/api-explorer) as well.
37
36
38
37
For example, on the screenshot below, you can see that to be able to use the Account Status, a token with read access level must be used.
39
38
40
39
41
40
42
-
Following the authorization of a Websocket connection, subsequent calls on that connection will be considered user actions.
41
+
Following the authorisation of a WebSocket connection, subsequent calls on that connection will be considered user actions.
43
42
44
43
Please bear in mind that the API token can be used with any app, so both your app and your clients need to keep it secure.
45
44
46
45
### OAuth2
47
46
48
-
OAuth stands for Open Authorization - a protocol that allows a client access resources hosted on a server on behalf of the user without revealing the credentials.
47
+
OAuth stands for `Open Authorisation` — a protocol that allows a client to access resources hosted on a server on behalf of the user without revealing the credentials.
49
48
50
-
This type of authorization allows clients to log in to third-party apps using their Deriv accounts without creating an API token. In this case, the third-party app does not see the user's password or permanent API token, which makes it safer.
49
+
This type of authorisation allows clients to log in to third-party apps using their Deriv accounts without creating an API token. In this case, the third-party app does not see the user's password or permanent API token, which makes it safer.
51
50
52
51
The OAuth2 authentication requires more steps to set up, but it is the safest way for developers to share access to their app with their clients.
53
52
54
53
For more information on OAuth2, visit [this guide](https://aaronparecki.com/oauth-2-simplified/).
55
54
56
-
Here is the visual representation of how the OAuth authorization connection works:
55
+
Here is the visual representation of how the OAuth authorisation connection works:
In order to Authenticate your user, specify the URL that will be used as the OAuth Redirect URL on the [Dashboard](/dashboard) page, **Register application** tab in the **OAuth details** fields and then Add a login button on your website or app and direct users to **`https://oauth.binary.com/oauth2/authorize?app_id=your_app_id`** where your_app_id is the ID of your app.
61
+
In order to authenticate your user, specify the URL that will be used as the OAuth Redirect URL on the [Dashboard](/dashboard) page, **Register application** tab in the **OAuth details** fields. Then, add a login button on your website or app and direct users to **`https://oauth.binary.com/oauth2/authorize?app_id=your_app_id`** where your_app_id is the ID of your app.
Once a user signs up / signs in, they will be redirected to the URL that you entered as the Redirect URL. This URL will have arguments added to it with the user's session tokens, and will look similar to this:
65
+
Once a user signs up/logs in, they will be redirected to the URL that you entered as the Redirect URL. This URL will have arguments added to it with the user's session tokens, and will look similar to this:
The query params in the redirect URL are the user's accounts and their related session tokens. you can map the query params to an array like so:
71
+
The query parameters in the redirect URL are the user's accounts and their related session tokens. You can map the query parameters to an array using the following approach:
73
72
74
73
```js
75
74
constuser_accounts= [
@@ -85,17 +84,14 @@ const user_accounts = [
85
84
},
86
85
];
87
86
```
88
-
89
-
To authorize the user, based on the user's **Selected** account, call the [authorize](https://api.deriv.com/api-explorer#authorize) API call with the user's **Selected** account **Session Token**:
90
-
87
+
To authorise the user based on the user's **selected** account, call the [authorize](https://api.deriv.com/api-explorer#authorize) API call with the user's **selected** account **session token**:
91
88
```js
92
89
{
93
90
"authorize":"a1-f7pnteezo4jzhpxclctizt27hyeot"
94
91
}
95
92
```
96
93
97
-
The response for the `authorize` call would be an object like so:
98
-
94
+
The response for the `authorize` call would be an object as below:
99
95
```js
100
96
{
101
97
"account_list": [
@@ -149,5 +145,4 @@ The response for the `authorize` call would be an object like so:
149
145
"user_id":12345678
150
146
}
151
147
```
152
-
153
-
Now user is authorized and you use Deriv API calls on behalf of the account.
148
+
Now, the user is authorised, and you can use Deriv API calls on behalf of the account.
0 commit comments