migrate_v5_EN_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 to connect to your SRS server.
The HTTP API of SRS follows the simple priciple:
- Only provides API in json format, both request and json are json.
- Please use srs-console to access API.
- When error, response in HTTP status or code in json.
SRS always enable the http api, read configure
./configure && makeThe config also need to enable it:
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.
# default: off
enabled off;
# whether enable rpc reload.
# default: off
allow_reload off;
# whether enable rpc query.
# default: off
allow_query off;
# whether enable rpc update.
# default: off
allow_update off;
}
# 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=CN/ST=Beijing/L=Beijing/O=Me/OU=Me/CN=ossrs.net"
# 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/diskstatsto get the right disk names, for instance, xvda.
Start SRS: ./objs/srs -c http-api.conf
Access api, open the url in web browser:
Remark: Please use your server ip instead.
The HTTP api supports 370 request per seconds, please test by AB(Apache Benchmark).
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:
# curl http://192.168.1.102:1985/
"urls": {
"api": "the api root"
}Go on:
# curl http://192.168.1.102:1985/api/v1/versions
"major": 0,
"minor": 9,
"revision": 43,
"version": "0.9.43"Or:
# 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.
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.
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
methodin 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})
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=CN/ST=Beijing/L=Beijing/O=Me/OU=Me/CN=ossrs.net"
# 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
SRS works very well with HTTP/HTTPS proxy, like Nginx, HTTPX, CaddyServer, etc. Please read #2881 for details.
Each response of api contains a server field, which identify the server. When ServerID changed, SRS already restarted, all information before is invalid.
SRS provides the nevigation 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 |
To push or publish stream to SRS using WebRTC, client should request the publish API to exchange SDP.
For example:
POST /rtc/v1/publish/
Body in JSON:
{
"api": "https://d.ossrs.net/rtc/v1/publish/"
"streamurl": "webrtc://d.ossrs.net/live/3abd9f34",
"sdp": "v=0\r\n......\r\na=ssrc:2064016335 label:c8243ce9-ace5-4d17-9184-41a2543101b5\r\n"
}
Server response the SDP for WebRTC:
{
"code": 0
"sdp": "v=0\r\n......\r\na=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0\r\n"
"sessionid": "186tj710:hMub"
}
Please see srs.sdk.js for detail.
To pull or play stream from SRS using WebRTC, please request the bellow API with the same request as WebRTC publish.
For example:
POST /rtc/v1/play/
Body in JSON:
{
"api": "https://d.ossrs.net/rtc/v1/play/"
"streamurl": "webrtc://d.ossrs.net/live/3abd9f34",
"sdp": "v=0\r\n......\r\na=ssrc:2064016335 label:c8243ce9-ace5-4d17-9184-41a2543101b5\r\n"
}
Server response the SDP for WebRTC:
{
"code": 0
"sdp": "v=0\r\n......\r\na=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0\r\n"
"sessionid": "186tj710:hMub"
}
Please see srs.sdk.js for detail.
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
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
SRS provides http api to query all streams.
The http api stream url: http://192.168.1.102:1985/api/v1/streams
To process specified stream by id, for instance http://192.168.1.102:1985/api/v1/streams/3756
SRS provides http api to query clients, default to get top 10 clients.
The http api client url: http://192.168.1.102:1985/api/v1/clients
To process specified client by id, for instance http://192.168.1.102:1985/api/v1/clients/3756
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 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 ""
This feature is disabled by SRS 4.0.
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.
Remark: 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:
| 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 |
| 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 are disabled by SRS 4.0.
Winlin 2015.8