--- 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. 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 | 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 ![](https://ossrs.io/gif/v1/sls.gif?site=ossrs.io&path=/lts/doc/en/v7/http-api)