534 lines
15 KiB
Markdown
534 lines
15 KiB
Markdown
---
|
|
title: HTTP API
|
|
sidebar_label: HTTP API
|
|
hide_title: false
|
|
hide_table_of_contents: false
|
|
---
|
|
|
|
# HTTP API
|
|
|
|
SRS provides HTTP api, to external application to manage SRS, and support crossdomain for js.
|
|
|
|
Once HTTP API enabled, you can use [srs-console](http://ossrs.net/console/) to connect to your SRS server.
|
|
|
|
The workflow is:
|
|
|
|
```text
|
|
+-------------------------+ +-------+
|
|
+ Chrome/Your Application +--HTTP-API-->--+ SRS +
|
|
+-------------------------+ +-------+
|
|
```
|
|
|
|
You can use Chrome or your application, to request the HTTP API of SRS to get the state of SRS.
|
|
|
|
## Goals
|
|
|
|
The HTTP API of SRS follows the simple priciple:
|
|
|
|
* Only provides API in json format, both request and response are json.
|
|
* Please use [srs-console](https://github.com/ossrs/srs-console) to access API.
|
|
* When error, response in HTTP status or code in json.
|
|
|
|
## Build
|
|
|
|
SRS always enable the http api, read [configure](./install.md)
|
|
|
|
```bash
|
|
./configure && make
|
|
```
|
|
|
|
## Config
|
|
|
|
The config also need to enable it:
|
|
|
|
```bash
|
|
listen 1935;
|
|
# system statistics section.
|
|
# the main cycle will retrieve the system stat,
|
|
# for example, the cpu/mem/network/disk-io data,
|
|
# the http api, for instance, /api/v1/summaries will show these data.
|
|
# @remark the heartbeat depends on the network,
|
|
# for example, the eth0 maybe the device which index is 0.
|
|
stats {
|
|
# the index of device ip.
|
|
# we may retrieve more than one network device.
|
|
# default: 0
|
|
network 0;
|
|
# the device name to stat the disk iops.
|
|
# ignore the device of /proc/diskstats if not configed.
|
|
disk sda sdb xvda xvdb;
|
|
}
|
|
# api of srs.
|
|
# the http api config, export for external program to manage srs.
|
|
# user can access http api of srs in browser directly, for instance, to access by:
|
|
# curl http://192.168.1.170:1985/api/v1/reload
|
|
# which will reload srs, like cmd killall -1 srs, but the js can also invoke the http api,
|
|
# where the cli can only be used in shell/terminate.
|
|
http_api {
|
|
# whether http api is enabled.
|
|
# default: off
|
|
enabled on;
|
|
# the http api listen entry is <[ip:]port>
|
|
# for example, 192.168.1.100:1985
|
|
# where the ip is optional, default to 0.0.0.0, that is 1985 equals to 0.0.0.0:1985
|
|
# default: 1985
|
|
listen 1985;
|
|
# whether enable crossdomain request.
|
|
# default: on
|
|
crossdomain on;
|
|
# the HTTP RAW API is more powerful api to change srs state and reload.
|
|
raw_api {
|
|
# whether enable the HTTP RAW API.
|
|
# Overwrite by env SRS_HTTP_API_RAW_API_ENABLED
|
|
# default: off
|
|
enabled off;
|
|
# whether enable rpc reload.
|
|
# Overwrite by env SRS_HTTP_API_RAW_API_ALLOW_RELOAD
|
|
# default: off
|
|
allow_reload off;
|
|
# whether enable rpc query.
|
|
# Always off by https://github.com/ossrs/srs/issues/2653
|
|
#allow_query off;
|
|
# whether enable rpc update.
|
|
# Always off by https://github.com/ossrs/srs/issues/2653
|
|
#allow_update off;
|
|
}
|
|
# the auth is authentication for http api
|
|
auth {
|
|
# whether enable the HTTP AUTH.
|
|
# Overwrite by env SRS_HTTP_API_AUTH_ENABLED
|
|
# default: off
|
|
enabled on;
|
|
# The username of Basic authentication:
|
|
# Overwrite by env SRS_HTTP_API_AUTH_USERNAME
|
|
username admin;
|
|
# The password of Basic authentication:
|
|
# Overwrite by env SRS_HTTP_API_AUTH_PASSWORD
|
|
password admin;
|
|
}
|
|
# For https_api or HTTPS API.
|
|
https {
|
|
# Whether enable HTTPS API.
|
|
# default: off
|
|
enabled on;
|
|
# The listen endpoint for HTTPS API.
|
|
# default: 1986
|
|
listen 1986;
|
|
# The SSL private key file, generated by:
|
|
# openssl genrsa -out server.key 2048
|
|
# default: ./conf/server.key
|
|
key ./conf/server.key;
|
|
# The SSL public cert file, generated by:
|
|
# openssl req -new -x509 -key server.key -out server.crt -days 3650 -subj "/C=CA/ST=Toronto/L=Toronto/O=Me/OU=Me/CN=ossrs.io"
|
|
# default: ./conf/server.crt
|
|
cert ./conf/server.crt;
|
|
}
|
|
}
|
|
vhost __defaultVhost__ {
|
|
}
|
|
```
|
|
|
|
The `http_api` enable the HTTP API, and `stats` used for SRS to stat the system info, including:
|
|
|
|
* network: Used for heartbeat to report the network info, where heartbeat used to report system info.
|
|
* disk: Used to stat the specified disk iops. You can use command `cat /proc/diskstats` to get the right disk names, for instance, xvda.
|
|
|
|
## Start
|
|
|
|
Start SRS: `./objs/srs -c http-api.conf`
|
|
|
|
Access api, open the url in web browser:
|
|
|
|
* [http://127.0.0.1:1985/api/v1](http://127.0.0.1:1985/api/v1)
|
|
* [https://127.0.0.1:1986/api/v1](https://127.0.0.1:1986/api/v1)
|
|
|
|
> Remark: Please use your server ip instead.
|
|
|
|
## Performance
|
|
|
|
The HTTP api supports 370 request per seconds, please test by AB(Apache Benchmark).
|
|
|
|
## Access Api
|
|
|
|
Use web brower, or curl, or other http library.
|
|
|
|
SRS provides api urls list, no need to remember:
|
|
* code, an int error code. 0 is success.
|
|
* urls, the url lists, can be access.
|
|
* data, the last level api serve data.
|
|
|
|
Root directory:
|
|
|
|
```bash
|
|
# curl http://192.168.1.102:1985/
|
|
"urls": {
|
|
"api": "the api root"
|
|
}
|
|
```
|
|
|
|
Go on:
|
|
|
|
```bash
|
|
# curl http://192.168.1.102:1985/api/v1/versions
|
|
"major": 0,
|
|
"minor": 9,
|
|
"revision": 43,
|
|
"version": "0.9.43"
|
|
```
|
|
|
|
Or:
|
|
|
|
```bash
|
|
# curl http://192.168.1.102:1985/api/v1/authors
|
|
"primary_authors": "xxx",
|
|
"contributors_link": "https://github.com/ossrs/srs/blob/master/AUTHORS.txt",
|
|
"contributors": "xxx"
|
|
```
|
|
|
|
The Api of SRS is self-describes api.
|
|
|
|
## Error Code
|
|
|
|
SRS response error in both HTTP status or HTTP body.
|
|
|
|
For example, SRS response HTTP error, where HTTP status not 200:
|
|
|
|
```
|
|
winlin:~ winlin$ curl -v http://127.0.0.1:1985 && echo ""
|
|
< HTTP/1.1 404 Not Found
|
|
< Connection: Keep-Alive
|
|
< Content-Length: 9
|
|
< Content-Type: text/plain; charset=utf-8
|
|
< Server: SRS/2.0.184
|
|
<
|
|
Not Found
|
|
```
|
|
|
|
For example, SRS response code not 0 when HTTTP Status 200:
|
|
|
|
```
|
|
winlin:~ winlin$ curl -v http://127.0.0.1:1985/api/v1/tests/errors && echo ""
|
|
< HTTP/1.1 200 OK
|
|
< Connection: Keep-Alive
|
|
< Content-Length: 12
|
|
< Content-Type: application/json
|
|
< Server: SRS/2.0.184
|
|
<
|
|
{"code":100}
|
|
```
|
|
|
|
User should handle these two error style.
|
|
|
|
## Crossdomain
|
|
|
|
SRS HTTP API supports js crossdomain, so the html/js can invoke http api of srs。
|
|
|
|
SRS support two main CROS styles:
|
|
|
|
* OPTIONS: JQuery can directly access the CROS, where the brower will send an OPTIONS first, then the API request.
|
|
* JSONP: JQuery/Angularjs can send JSONP CROS request to SRS API, where specifes the function name by QueryString `callback`.
|
|
* JSONP-DELETE: JSONP only support GET, so we use the `method` in QueryString to override the HTTP method for JSONP.
|
|
|
|
For example, the JSONP crossdomain request:
|
|
|
|
```
|
|
GET http://localhost:1985/api/v1/vhosts/?callback=JSON_CALLBACK
|
|
JSON_CALLBACK({"code":0,"server":13449})
|
|
GET http://localhost:1985/api/v1/vhosts/100?callback=JSON_CALLBACK&method=DELETE
|
|
JSON_CALLBACK({"code":0})
|
|
```
|
|
|
|
## HTTPS API
|
|
|
|
SRS supports HTTPS API by turn the `https` on:
|
|
|
|
```
|
|
http_api {
|
|
enabled on;
|
|
listen 1985;
|
|
https {
|
|
# Whether enable HTTPS API.
|
|
# default: off
|
|
enabled on;
|
|
# The listen endpoint for HTTPS API.
|
|
# default: 1990
|
|
listen 1990;
|
|
# The SSL private key file, generated by:
|
|
# openssl genrsa -out server.key 2048
|
|
# default: ./conf/server.key
|
|
key ./conf/server.key;
|
|
# The SSL public cert file, generated by:
|
|
# openssl req -new -x509 -key server.key -out server.crt -days 3650 -subj "/C=CA/ST=Toronto/L=Toronto/O=Me/OU=Me/CN=ossrs.io"
|
|
# default: ./conf/server.crt
|
|
cert ./conf/server.crt;
|
|
}
|
|
}
|
|
```
|
|
|
|
> Remark: Please use your HTTPS key and cert file.
|
|
|
|
> Note: To enable the HTTPS live streaming, please read [HTTPS FLV Live Stream](./flv.md#https-flv-live-stream)
|
|
|
|
## HTTP and HTTPS Proxy
|
|
|
|
SRS works well with HTTP/HTTPS proxies such as [Nginx](./http-server.md#nginx-proxy), [HTTPX](./http-server.md#httpx-proxy),
|
|
[CaddyServer](./http-server.md#caddy-proxy), and so on.
|
|
|
|
## Server ID
|
|
|
|
Each response of api contains a `server` field, which identify the server. When ServerID changed, SRS already restarted, all information before is invalid.
|
|
|
|
## API Navigation
|
|
|
|
SRS provides the Navigation of APIs.
|
|
|
|
User can access the `http://192.168.1.102:1985/api/v1`, where:
|
|
|
|
| API | Example | Description |
|
|
| --- | -------- | --------- |
|
|
| server | 4481 | The identity of SRS |
|
|
| versions | /api/v1/versions | the version of SRS |
|
|
| summaries | /api/v1/summaries | the summary(pid, argv, pwd, cpu, mem) of SRS |
|
|
| rusages | /api/v1/rusages | the rusage of SRS |
|
|
| self_proc_stats | /api/v1/self_proc_stats | the self process stats |
|
|
| system_proc_stats | /api/v1/system_proc_stats | the system process stats |
|
|
| meminfos | /api/v1/meminfos | the meminfo of system |
|
|
| authors | /api/v1/authors | the license, copyright, authors and contributors |
|
|
| features | /api/v1/features | the supported features of SRS |
|
|
| requests | /api/v1/requests | the request itself, for http debug |
|
|
| vhosts | /api/v1/vhosts | manage all vhosts or specified vhost |
|
|
| streams | /api/v1/streams | manage all streams or specified stream |
|
|
| clients | /api/v1/clients | manage all clients or specified client, default query top 10 clients |
|
|
| configs | /api/v1/configs | RAW API for CUID the configs |
|
|
| publish | /rtc/v1/publish/ | The push stream API for WebRTC |
|
|
| play | /rtc/v1/play/ | The play stream API for WebRTC |
|
|
|
|
## WebRTC Publish
|
|
|
|
In order to push stream over WebRTC to SRS, SRS supports [WHIP](https://datatracker.ietf.org/doc/draft-ietf-wish-whip/).
|
|
The request is defined as:
|
|
|
|
```text
|
|
POST /rtc/v1/whip/?app=live&stream=livestream
|
|
|
|
Body in SDP, the Content-type is application/sdp:
|
|
|
|
v=0
|
|
......
|
|
a=ssrc:2064016335 label:c8243ce9-ace5-4d17-9184-41a2543101b5
|
|
```
|
|
|
|
SRS responses the SDP answer as the HTTP response:
|
|
|
|
```text
|
|
v=0
|
|
......
|
|
a=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0
|
|
```
|
|
|
|
> Note: The HTTP Status is 201, not 200, according to WHIP specification.
|
|
|
|
Please also see examples at [srs.sdk.js](https://github.com/ossrs/srs/blob/develop/trunk/research/players/js/srs.sdk.js) and [srs-unity: Publisher](https://github.com/ossrs/srs-unity#usage-publisher).
|
|
|
|
## WebRTC Play
|
|
|
|
In order to pull stream over WebRTC from SRS, SRS also supports [WHEP](https://datatracker.ietf.org/doc/draft-murillo-whep/).
|
|
The request is defined as:
|
|
|
|
```text
|
|
POST /rtc/v1/whep/?app=live&stream=livestream
|
|
|
|
Body in SDP, the Content-type is application/sdp:
|
|
|
|
v=0
|
|
......
|
|
a=ssrc:2064016335 label:c8243ce9-ace5-4d17-9184-41a2543101b5
|
|
```
|
|
|
|
> Note: Although WHIP is defined to push stream to SRS, but you're able to use it for pulling stream from SRS. There is another [WHEP](https://datatracker.ietf.org/doc/draft-murillo-whep/) for players, but not a RFC draft.
|
|
|
|
SRS responses the SDP answer as the HTTP response:
|
|
|
|
```
|
|
v=0
|
|
......
|
|
a=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0
|
|
```
|
|
|
|
> Note: The HTTP Status is 201, not 200, according to WHIP specification.
|
|
|
|
Please also see examples at [srs.sdk.js](https://github.com/ossrs/srs/blob/develop/trunk/research/players/js/srs.sdk.js) and [srs-unity: Player](https://github.com/ossrs/srs-unity#usage-player).
|
|
|
|
## Summaries
|
|
|
|
User can get the system summaries, for instance, the memory, cpu, network, load usage.
|
|
|
|
Please access the url `http://192.168.1.170:1985/api/v1/summaries`
|
|
|
|
## Vhosts
|
|
|
|
SRS provides http api to query all vhosts.
|
|
|
|
The http api vhost url: `http://192.168.1.102:1985/api/v1/vhosts`
|
|
|
|
To process specified vhost by id, for instance `http://192.168.1.102:1985/api/v1/vhosts/3756`
|
|
|
|
## Streams
|
|
|
|
SRS provides http api to query all streams.
|
|
|
|
The http api stream url: `http://192.168.1.102:1985/api/v1/streams`
|
|
|
|
Parameters in query string:
|
|
|
|
* `?start=N`: The start index, default is 0.
|
|
* `?count=N`: The max number of result, default is 10.
|
|
|
|
To process specified stream by id, for instance `http://192.168.1.102:1985/api/v1/streams/3756`
|
|
|
|
## Clients
|
|
|
|
SRS provides http api to query clients.
|
|
|
|
The http api client url: `http://192.168.1.102:1985/api/v1/clients`
|
|
|
|
Parameters in query string:
|
|
|
|
* `?start=N`: The start index, default is 0.
|
|
* `?count=N`: The max number of result, default is 10.
|
|
|
|
To process specified client by id, for instance `http://192.168.1.102:1985/api/v1/clients/3756`
|
|
|
|
## Kickoff Client
|
|
|
|
SRS provides HTTP RESTful api to kickoff user:
|
|
|
|
```
|
|
DELETE /api/v1/clients/{id}
|
|
```
|
|
|
|
User can get the id of client to kickoff:
|
|
|
|
```
|
|
GET /api/v1/clients
|
|
```
|
|
|
|
User can get the id of publish client from streams api:
|
|
|
|
```
|
|
GET /api/v1/streams
|
|
or GET /api/v1/streams/6745
|
|
```
|
|
|
|
The client cid is the info from stream api `stream.publish.cid`:
|
|
|
|
```
|
|
1. GET http://192.168.1.170:1985/api/v1/streams/6745
|
|
2. Response stream.publish.cid:
|
|
stream: {
|
|
publish: {
|
|
active: true,
|
|
cid: 107
|
|
}
|
|
}
|
|
3. DELETE http://192.168.1.170:1985/api/v1/clients/107
|
|
```
|
|
|
|
Remark: User can use [HTTP REST Tool](http://ossrs.net/srs.release/http-rest/index.html) to send a request.
|
|
|
|
Remark: User can use linux tool `curl` to start HTTP request. For example:
|
|
|
|
```
|
|
curl -v -X GET http://192.168.1.170:1985/api/v1/clients/426 && echo ""
|
|
curl -v -X DELETE http://192.168.1.170:1985/api/v1/clients/426 && echo ""
|
|
```
|
|
|
|
## Persistence Config
|
|
|
|
This feature is disabled by SRS 4.0.
|
|
|
|
## HTTP RAW API
|
|
|
|
SRS supports powerful HTTP RAW API, while other server only support `Read API`, for instance, to get the stat of server. SRS supports `Write API`, which can `Reload` or change server state.
|
|
|
|
<b>Remark:</b> User must enable the HTTP RAW API, in config section `http_api` to enable the `http_api.raw_api.enabled`, or SRS will response error code 1061.
|
|
|
|
```
|
|
http_api {
|
|
enabled on;
|
|
listen 1985;
|
|
raw_api {
|
|
enabled on;
|
|
allow_reload on;
|
|
}
|
|
}
|
|
```
|
|
|
|
The supported HTTP RAW APi of SRS is:
|
|
|
|
* `Raw`: To query the HTTP RAW API config.
|
|
* `Reload`: To reload the SRS.
|
|
|
|
### Raw
|
|
|
|
| Key | DESC |
|
|
| ---- | ---- |
|
|
| feature | Query the HTTP RAW API info. |
|
|
| url | `/api/v1/raw?rpc=raw` |
|
|
| curl | `curl http://127.0.0.1:1985/api/v1/raw?rpc=raw` |
|
|
| config | No config |
|
|
| params | No params|
|
|
|
|
### RAW Reload
|
|
|
|
| Key | DESC |
|
|
| ---- | ---- |
|
|
| feature | Reload is the same to `killall -1 srs` to reload the config |
|
|
| url | `/api/v1/raw?rpc=reload` |
|
|
| curl | `curl http://127.0.0.1:1985/api/v1/raw?rpc=reload` |
|
|
| params | No params |
|
|
|
|
### Other RAW APIs
|
|
|
|
Other RAW APIs are disabled by SRS 4.0.
|
|
|
|
## Authentication
|
|
|
|
Starting from version `5.0.152+` or `6.0.40+`, SRS supports HTTP API authentication, which can be enabled by configuring `http_api.auth`.
|
|
|
|
```bash
|
|
# conf/http.api.auth.conf
|
|
http_api {
|
|
enabled on;
|
|
listen 1985;
|
|
auth {
|
|
enabled on;
|
|
username admin;
|
|
password admin;
|
|
}
|
|
}
|
|
```
|
|
|
|
Otherwise, you can use environment variables to enable it:
|
|
|
|
```bash
|
|
env SRS_HTTP_API_ENABLED=on SRS_HTTP_SERVER_ENABLED=on \
|
|
SRS_HTTP_API_AUTH_ENABLED=on SRS_HTTP_API_AUTH_USERNAME=admin SRS_HTTP_API_AUTH_PASSWORD=admin \
|
|
./objs/srs -e
|
|
```
|
|
|
|
Then, you can access the following urls to verify it:
|
|
- Prompt for username and password: http://localhost:1985/api/v1/versions
|
|
- URL with authentication: http://admin:admin@localhost:1985/api/v1/versions
|
|
|
|
To clean up the username and password, you can access the HTTP API with the username only:
|
|
- http://admin@localhost:1985/api/v1/versions
|
|
|
|
> Note: authentication is only enabled for the HTTP APIs, neither for the HTTP server nor the WebRTC HTTP APIs.
|
|
|
|
Winlin 2015.8
|
|
|
|
|
|
|
|
|