Skip to main content
Version: 7.0 (Unstable) 🚧

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 workflow is:

+-------------------------+               +-------+
+ 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 to access API.
  • When error, response in HTTP status or code in json.

Build

SRS always enable the http api, read configure

./configure && make

Config

The 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.
        # 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=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/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:

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:

# 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.

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=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

HTTP and HTTPS Proxy

SRS works well with HTTP/HTTPS proxies such as Nginx, HTTPX, CaddyServer, 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:

APIExampleDescription
server4481The identity of SRS
versions/api/v1/versionsthe version of SRS
summaries/api/v1/summariesthe summary(pid, argv, pwd, cpu, mem) of SRS
rusages/api/v1/rusagesthe rusage of SRS
self_proc_stats/api/v1/self_proc_statsthe self process stats
system_proc_stats/api/v1/system_proc_statsthe system process stats
meminfos/api/v1/meminfosthe meminfo of system
authors/api/v1/authorsthe license, copyright, authors and contributors
features/api/v1/featuresthe supported features of SRS
requests/api/v1/requeststhe request itself, for http debug
vhosts/api/v1/vhostsmanage all vhosts or specified vhost
streams/api/v1/streamsmanage all streams or specified stream
clients/api/v1/clientsmanage all clients or specified client, default query top 10 clients
configs/api/v1/configsRAW 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. The request is defined as:

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:

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 and srs-unity: Publisher.

WebRTC Play

In order to pull stream over WebRTC from SRS, SRS also supports WHEP. The request is defined as:

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 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 and srs-unity: 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 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.

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:

  • Raw: To query the HTTP RAW API config.
  • Reload: To reload the SRS.

Raw

KeyDESC
featureQuery the HTTP RAW API info.
url/api/v1/raw?rpc=raw
curlcurl http://127.0.0.1:1985/api/v1/raw?rpc=raw
configNo config
paramsNo params

RAW Reload

KeyDESC
featureReload is the same to killall -1 srs to reload the config
url/api/v1/raw?rpc=reload
curlcurl http://127.0.0.1:1985/api/v1/raw?rpc=reload
paramsNo 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.

# 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:

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:

To clean up the username and password, you can access the HTTP API with the username only:

Note: authentication is only enabled for the HTTP APIs, neither for the HTTP server nor the WebRTC HTTP APIs.

Winlin 2015.8

©2013~2024 OSSRS Community