REST¶

oTree has a REST API that enables external programs (such as other websites) to communicate with oTree.

REST API是一个在你的服务器上被设计用来被其他程序使用的URL，而不是用于在浏览器中手动打开的。

One project that uses the REST API a lot is oTree HR.

警告

As of March 2021, there have been some breaking changes to the REST API.

Setup¶

注解

“这些代码应当放在哪里”

这些代码无需包含在你的oTree项目文件夹中。由于REST API的关键就在于使得外部程序和服务器可以与oTree通过网络通信，你应当将这些代码放在其他程序中。这意味着你可以使用在其他服务器上适用的任何语言来编写程序。本页面上的例子使用的是Python，但是使用其他编程语言进行HTTP请求也很简单，如webhooks工具或者cURL。

import requests  # pip3 install requests
from pprint import pprint


GET = requests.get
POST = requests.post

# if using Heroku, change this to https://YOURAPP.herokuapp.com
SERVER_URL = 'http://localhost:8000'
REST_KEY = ''  # fill this later

def call_api(method, *path_parts, **params) -> dict:
    path_parts = '/'.join(path_parts)
    url = f'{SERVER_URL}/api/{path_parts}/'
    resp = method(url, json=params, headers={'otree-rest-key': REST_KEY})
    if not resp.ok:
        msg = (
            f'Request to "{url}" failed '
            f'with status code {resp.status_code}: {resp.text}'
        )
        raise Exception(msg)
    return resp.json()

“oTree version” endpoint¶

注解

New beta feature as of March 2021.

GET URL: /api/otree_version/

例子¶

data = call_api(GET, 'otree_version')
# returns: {'version': '5.0.0'}

“Session configs” endpoint¶

注解

New beta feature as of March 2021.

GET URL: /api/session_configs/

Returns the list of all your session configs, as dicts with all their properties.

例子¶

data = call_api(GET, 'session_configs')
pprint(data)

“Rooms” endpoint¶

注解

New beta feature as of March 2021.

GET URL: /api/rooms/

例子¶

data = call_api(GET, 'session_configs')
pprint(data)

Example output (note it includes session_code if there is currently a session in the room):

[{'name': 'my_room',
  'session_code': 'lq3cxfn2',
  'url': 'http://localhost:8000/room/my_room'},
 {'name': 'live_demo',
  'session_code': None,
  'url': 'http://localhost:8000/room/live_demo'}]

“Create sessions” endpoint¶

POST URL: /api/sessions/

下面是一些”create sessions”路径应当如何使用的例子：

其他网站可自动创建oTree会话
你可以自己创造一个更好看的oTree 配置会话界面（例如加上侧边栏和控件）
在某些固定时刻创建oTree会话的进程
创建自定义会话的命令行脚本（如果 otree create_session 不够用的话）

例子¶

data = call_api(
    POST,
    'sessions',
    session_config_name='trust',
    room_name='econ101',
    num_participants=4,
    modified_session_config_fields=dict(num_apples=10, abc=[1, 2, 3]),
)
pprint(data)

参数¶

session_config_name (必要)
num_participants (必要)
modified_session_config_fields: 一个可选的包含session config参数的字典，详见配置会话.
room_name 如果你想在房间中创建session。

“Get session data” endpoint¶

注解

New feature as of March 2021. In beta until we get sufficient user feedback.

GET URL: /api/sessions/{code}

This API retrieves data about a session and its participants. If participant_labels is omitted, it returns data for all participants.

例子¶

data = call_api(GET, 'sessions', 'vfyqlw1q', participant_labels=['Alice'])
pprint(data)

“Session vars” endpoint¶

注解

As of April 2021, this endpoint requires you to pass a session code as a path parameter. If the session is in a room, you can get the session code with the rooms endpoint.

POST URL: /api/session_vars/{session_code}

这一路径使你可以设置 session.vars。一种用途是实验输入。举例来说，如果实验中有一次抽奖，就可以通过运行下面的脚本来输入结果。

例子¶

call_api(POST, 'session_vars', 'vfyqlw1q', vars=dict(dice_roll=4))

“Participant vars” endpoint¶

POST URL: /api/participant_vars/{participant_code}

Pass information about a participant to oTree, via web services / webhooks.

例子¶

call_api(POST, 'participant_vars', 'vfyqlw1q', vars=dict(birth_year='1995', gender='F'))

“Participant vars for room” endpoint¶

POST URL: /api/participant_vars/

Similar to the other “participant vars” endpoint, but this one can be used when you don’t have the participant’s code. Instead, you identify the participant by the room name and their participant label.

例子¶

call_api(
    POST,
    'participant_vars',
    room_name='qualtrics_study',
    participant_label='albert_e',
    vars=dict(age=25, is_male=True, x=[3, 6, 9]),
)

参数¶

room_name (必要)
participant_label (必要)
vars (必要): 用于加入participant vars的字典，其中值必须是可被JSON序列化的数据类型, 甚至可以是嵌套的字典/列表。

You will need to give participants a link with a participant_label, although this does not need to come from a participant_label_file.

认证¶

如果你将你的验证等级从DEMO改为STUDY，你必须验证你的REST API请求。

在服务器上创建一个环境变量（即 Heroku config var） OTREE_REST_KEY 。将其设置为某个秘密值。

When you make a request, add that key as an HTTP header called otree-rest-key. If following the setup example above, you would set the REST_KEY variable.

演示 & 测试¶

为在开发时更便利，你可以在一个真实的会话中生成假的vars来模拟从REST API获得的数据。

在你的session config中，添加参数 mock_exogenous_data=True (称其为 exogenous(外源性) 数据是因为其是在oTree外部生成的。)

然后在你的项目的shared_out.py中（如果你使用的是文本编辑器，你可能需要创建此文件）定义一个同名函数(mock_exogenous_data)。

下面是一个例子：

def mock_exogenous_data(session):
    participants = session.get_participants()
    for pp in participants:
        pp.vars.update(age=20, is_male=True) # or make it random

你也可以在此处设置参与人标签。

当你的会话运行在demo模式下，或者使用bot， mock_exogenous_data() 会在 creating_session 之后自动运行。然而，如果是在房间里创建的会话则不会运行。

如果你有多个session config需要不同的外源性数据，你可以像下面这样区分它们：

def mock_exogenous_data(session):
    if session.config['name'] == 'whatever':
        ...
    if 'xyz' in session.config['app_sequence']:
        ...