Skip to main content
版本：7.0 (Unstable) 🚧

HTTP API

SRS提供HTTP接口，供外部程序管理服务器，并支持跨域（js可以直接控制和获取服务器的各种信息）。

通过HTTP API，可以使用srs-console连接到你的服务器。

工作流如下：

+-------------------------+               +-------+
+ Chrome/Your Application +--HTTP-API-->--+  SRS  +
+-------------------------+               +-------+

您可以使用 Chrome 或您的应用程序，请求 SRS 的 HTTP API 以获取 SRS 的状态。

Goals

SRS的HTTP接口遵循最简单原则，主要包括：

  • 只提供json数据格式接口，要求请求和响应的数据全都是json。
  • srs-console可访问SRS的API，提供管理后台。
  • 发生错误时，支持HTTP错误码，或者json中的code错误码。

Build

SRS自动打开HTTPApi选项，参考：configure选项

./configure && make

Config

配置文件需要开启http-api：

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__ {
}

其中，http_api开启了HTTP API，stats配置了SRS后台统计的信息，包括：

  • network: 这个配置了heartbeat使用的网卡ip，即SRS主动汇报的网卡信息。
  • disk: 这个配置了需要统计的磁盘的IOPS，可以通过cat /proc/diskstats命令获得名称，譬如阿里云的磁盘名称叫xvda.

Start

启动服务器：./objs/srs -c http-api.conf

访问api，浏览器打开地址:

注意：请将192.168.1.170或者下面提到的任何服务器IP，换成您的服务器的IP。

Performance

机器：虚拟机CentOS6-64位，4CPU，T430笔记本，VirtualBox

10%CPU，10000次请求，27秒，平均370次请求/秒，30毫秒一个请求

top - 09:59:49 up 3 days, 50 min,  4 users,  load average: 0.00, 0.00, 0.00
Tasks: 140 total,   1 running, 139 sleeping,   0 stopped,   0 zombie
Cpu(s): 11.6%us, 20.0%sy,  0.0%ni, 66.7%id,  0.0%wa,  0.0%hi,  1.8%si,  0.0%st
Mem:   2055440k total,   990148k used,  1065292k free,   228544k buffers
Swap:  2064376k total,        0k used,  2064376k free,   486620k cached
  PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
29696 winlin    20   0 15872 1592 1360 S  9.3  0.1   0:14.21 ./objs/srs -c console.conf

[winlin@dev6 srs]$ time for((i=0;i<10000;i++)); do curl http://127.0.0.1:1985/api >/dev/null 2>&1; done

real	0m27.375s
user	0m8.223s
sys	0m16.289s

Access Api

直接在浏览器中就可以访问，或者用curl发起http请求。

SRS提供了api的面包屑，可以从根目录开始导航，不需要任何记忆。一般的字段包括：

  • code表示错误码，按照linux惯例，0表示成功。
  • urls表示是面包屑导航，该api下面的子api（链接）。
  • data表示最后一级提供服务的api，返回的数据。

另外，提供服务的api按照HTTP RESTful规则是复数，譬如versions/authors，表示资源。HTTP的各种方法表示操作，譬如GET查询，PUT更新，DELETE删除。参考：Redmine HTTP Rest api

根目录：

# curl http://192.168.1.170:1985/
    "urls": {
        "api": "the api root"
    }

继续：

# curl http://192.168.1.170:1985/api/v1/versions
        "major": 0,
        "minor": 9,
        "revision": 43,
        "version": "0.9.43"

或者：

# curl http://192.168.1.170:1985/api/v1/authors
        "primary_authors": "xxx",
        "contributors_link": "https://github.com/ossrs/srs/blob/master/AUTHORS.txt",
        "contributors": "xxx"

SRS的API属于“自解释型，HTTP RESTful API”

Error Code

SRS可能返回HTTP错误，即Status不等于200；或者在HTTP Status为200时，响应的json的code不为0.

譬如，返回HTTP错误：

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

譬如，HTTP200时内容中code不等于0：

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}

用户应该处理这两种错误。

Crossdomain

SRS HTTP API支持跨域，js可以直接调用srs的http api。

SRS支持两种跨域方式：

  • OPTIONS: jquery可以直接跨域请求API，浏览器会发送一个OPTIONS跨域请求，SRS允许跨域后，浏览器再次发起API请求。
  • JSONP: jquery/angularjs可以发起JSONP跨域请求，服务器会将响应作为js文件，内容是调用一个函数，函数名由QueryString中的callback指定。
  • JSONP-DELETE: JSONP只能GET，因此DELETE方法是由QueryString的method指定的。

JSONP实例，例如：

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内置支持HTTPS API，只需要开启配置https：

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: 请使用你的证书文件，代替上面配置中的key和cert。

Note: 若需要开启HTTPS直播流，请参考HTTPS FLV Live Stream

HTTP and HTTPS Proxy

SRS可以和HTTP/HTTPS代理一起工作得很好，比如Nginx, HTTPX, CaddyServer, 等等。

Server ID

SRS返回的api中都会带有server的信息，即Server的ID，用来标识服务器。客户端在获取信息时，必须检查ServerID是否改变，改变时就是服务器重启，之前所有的数据都应该作废了。

API Navigation

SRS提供了API的导航，即所有支持的API及描述。

地址是：http://192.168.1.170:1985/api/v1，主要包含的子api有：

APIExampleDescription
server4481服务器标识
versions/api/v1/versions获取服务器版本信息
summaries/api/v1/summaries获取服务器的摘要信息
rusages/api/v1/rusages获取服务器资源使用信息
self_proc_stats/api/v1/self_proc_stats获取服务器进程信息
system_proc_stats/api/v1/system_proc_stats获取服务器所有进程情况
meminfos/api/v1/meminfos获取服务器内存使用情况
authors/api/v1/authors获取作者、版权和License信息
features/api/v1/features获取系统支持的功能列表
requests/api/v1/requests获取请求的信息，即当前发起的请求的详细信息
vhosts/api/v1/vhosts获取服务器上的vhosts信息
streams/api/v1/streams获取服务器的streams信息
clients/api/v1/clients获取服务器的clients信息，默认获取前10个
configs/api/v1/configsCUID配置，RAW API
publish/rtc/v1/publish/WebRTC推流的API
play/rtc/v1/play/WebRTC播放流的API

WebRTC Publish

使用WebRTC推流到SRS时，需要先调用API交换SDK，SRS支持WHIP协议。例如：

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

服务器响应对应的SDP如下：

v=0
......
a=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0

Note: 按照WHIP的要求，响应的HTTP Status是201，而不是200。

具体调用和使用请参考srs.sdk.js和srs-unity: Publisher。

WebRTC Play

拉流或播放时，需要调用另外的API，请求格式和publish一样，SRS支持WHEP协议。例如：

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: 虽然WHIP是推流的协议，但是实际上也可以支持播放流，差异只在SDP中；当然有专门为播放涉及的WHEP，目前还没有RFC草案。

服务器响应对应的SDP如下：

v=0
......
a=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0

Note: 按照WHIP的要求，响应的HTTP Status是201，而不是200。

具体调用和使用请参考srs.sdk.js和srs-unity: Player。

Summaries

SRS提供系统的摘要信息接口，譬如当前的内存、CPU、网络、负载使用率。

地址为：http://192.168.1.170:1985/api/v1/summaries

Vhosts

SRS提供获取所有vhost的接口。

地址为：http://192.168.1.170:1985/api/v1/vhosts

还可以继续处理某个vhost的信息，譬如http://192.168.1.170:1985/api/v1/vhosts/3756

响应内容：

  • vhost中的server为srs的id，用来标识是否服务器重启了。

Streams

SRS提供获取所有stream的接口。

地址为：http://192.168.1.170:1985/api/v1/streams

参数：

  • ?start=N: 开始的索引，默认0。
  • ?count=N: 返回的总数目，默认为10。

还可以继续处理某个stream的信息，譬如http://192.168.1.170:1985/api/v1/streams/3756

响应内容：

  • stream中的server为srs的id，用来标识是否服务器重启了。
  • vhost为stream所属的vhost的id。

Clients

SRS提供查询客户端信息的接口。

地址为：http://192.168.1.170:1985/api/v1/clients

参数：

  • ?start=N: 开始的索引，默认0。
  • ?count=N: 返回的总数目，默认为10。

还可以继续处理某个client的信息，譬如http://192.168.1.170:1985/api/v1/clients/3756

Kickoff Client

可以踢掉连接的用户，SRS提供了HTTP RESTful接口：

DELETE /api/v1/clients/{id}

可以先查询到需要踢掉的Client的ID：

GET /api/v1/clients

若需要踢掉推流的Client，可以从streams接口中查询推流client的id：

GET /api/v1/streams
or GET /api/v1/streams/6745

流信息中的stream.publish.cid就是推流的客户端id：

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

备注：HTTP请求可以使用HTTP REST Tool

备注：HTTP请求还可以使用Linux的工具curl，常见的请求如下：

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

保存日志文件的功能，已经在4.0禁用了。

HTTP RAW API

SRS支持RAW API，一般的服务器只能提供读(Read)形式的API，譬如获取系统状态之类，但是SRS提供写(Write)形式的API，譬如Reload和修改系统配置等所有改写系统的行为。

注意: 必须在http_api配置中，开启http_api.raw_api.enabled才能允许HTTP RAW API，否则会返回错误代码是1061。

http_api {
    enabled         on;
    listen          1985;
    raw_api {
        enabled             on;
        allow_reload        on;
    }
}

SRS支持的HTTP RAW API包括：

  • Raw: 查看HTTP RAW API的配置。
  • Reload: 支持reload配置。

Raw

KeyDESC
feature查询服务器端HTTP RAW API的配置
url/api/v1/raw?rpc=raw
curlcurl http://127.0.0.1:1985/api/v1/raw?rpc=raw
config不需要
params无参数

RAW Reload

KeyDESC
feature可以重新加载配置，和killall -1 srs的效果是一样的
url/api/v1/raw?rpc=reload
curlcurl http://127.0.0.1:1985/api/v1/raw?rpc=reload
configallow_reload on;
params无参数

Other RAW APIs

其他RAW API已经在4.0中删除了。

Authentication

SRS在5.0.152+或者6.0.40+版本开始支持HTTP API鉴权，可以通过配置http_api.auth开启。

# conf/http.api.auth.conf
http_api {
    enabled on;
    listen 1985;
    auth {
        enabled on;
        username admin;
        password admin;
    }
}

或者，通过环境变量设置用户名和密码：

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

可以访问下面的地址来验证：

要清除用户名和密码，可以通过用户名访问HTTP API：

注意：只针对HTTP API开启了鉴权，不包括HTTP服务器和WebRTC HTTP API。

Winlin 2015.8

©2013~2024 OSSRS 京ICP备19056366号-1