Skip to content
Snippets Groups Projects
Verified Commit bacdf450 authored by Cecylia Bocovich's avatar Cecylia Bocovich
Browse files

Add documentation of resources GET endpoint

parent 822e0c19
No related branches found
Tags tor-0.4.3.3-alpha
1 merge request!67Add documentation for the rdsys backend API
......@@ -3,10 +3,10 @@ Backend API Documentation for Distributors
Distributors are standalone executables that communicate with the rdsys backend to receive updated information on resources. This documentation specifies the form that this IPC takes.
The recommended way to receive timely updates from the backend is to open and maintain a presistent HTTP connection to the backend api endpoint. The backend will periodically issue "resouce diffs" with relevant information on new, changed, or removed resources.
The recommended way to receive timely updates from the backend is to open and maintain a presistent HTTP connection to the backend api `resource-stream` endpoint. The backend will periodically issue "resouce diffs" with relevant information on new, changed, or removed resources. Alternatively, distributors can use the `resources` endpoint to either `GET` a full list of resources for a given distributor or `POST` to add new resources to the backend.
### Initiating a resource stream
The resource stream is initiated by the distributor by making a GET request to the `resource-stream` endpoint with data:
The resource stream is initiated by the distributor by making a `GET` request to the `resource-stream` endpoint with data:
`GET /resource-stream HTTP/1.1`
......@@ -33,12 +33,12 @@ where:
```
GET /resource-stream HTTP/1.1
Host: 127.0.0.1:7100
Authorization: Bearer HttpsPlaceholderToken
Content-Length: 68
Host: localhost:7100
Authorization: Bearer HttpsApiTokenPlaceholder
Content-Type: application/json
Content-Length: 68
{"request_origin":"https","resouce_types":["obfs2","scramblesuit"]}
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
```
</details>
......@@ -201,3 +201,124 @@ where:
```
</details>
### Making a static request for resources
Distributors also have the option to make a `GET` request to the `resources` endpoint for a full static list of all resources available for the given distribution method. As opposed to the resource stream, the HTTP response body will contain only a single resource diff
`GET /resources HTTP/1.1`
##### Headers
- `Host:` must be set
- `Authorization: Bearer [token]` must be set to the API bearer token
- `Content-Length:` must be set to the length of the supplied data for GET requests
##### Data
Distributors must send a JSON object with the following data:
```
{
"request_origin": string,
"resouce_types": [string]
}
```
where:
- `request_origin` is a string with the name of the distributor. This must correspond to a known distributor, specified in the config file for the rdsys backend.
- `resource_types` is a list of strings of requested resource types (e.g., "vanilla", "obfs4", "snowflake", etc.). Unknown resource types will be ignored.
<details>
<summary>Example:</summary>
```
GET /resources HTTP/1.1
Host: localhost:7100
Authorization: Bearer HttpsApiTokenPlaceholder
Content-Type: application/json
Content-Length: 68
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
```
</details>
### Response
The HTTP response to the `GET` resources API call is a chunked transfer encoding of a list of JSON objects that represent all the resources currently allocated to the distributor.
```
[
Resource,
Resource,
...
Resource
]
```
where `Resource` is specified above.
<details>
<summary>Example:</summary>
```
[
{
"type": "obfs2",
"blocked_in": {},
"Location": null,
"protocol": "tcp",
"address": "176.247.216.207",
"port": 42810,
"fingerprint": "10282810115283F99ADE5CFE42D49644F45D715D",
"or-addresses": null,
"distribution": "https",
"flags": {
"fast": true,
"stable": true,
"running": true,
"valid": true
}
},
{
"type": "obfs2",
"blocked_in": {},
"Location": null,
"protocol": "tcp",
"address": "133.69.16.145",
"port": 58314,
"fingerprint": "BE84A97D02130470A1C77839954392BA979F7EE1",
"or-addresses": null,
"distribution": "https",
"flags": {
"fast": true,
"stable": true,
"running": true,
"valid": true
}
},
{
"type": "scramblesuit",
"blocked_in": {},
"Location": null,
"protocol": "tcp",
"address": "216.117.3.62",
"port": 63174,
"fingerprint": "BE84A97D02130470A1C77839954392BA979F7EE1",
"or-addresses": null,
"distribution": "https",
"flags": {
"fast": true,
"stable": true,
"running": true,
"valid": true
},
"params": {
"password": "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
}
}
]
```
</details>
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment