A brief documentation is provided here to get started. For full specs, consult the Functional Specifications document.
List available box types
To list the available box types:
GET https://nonlocalbox.wigner.hu/api/v1/listBoxTypes?apiKey=$API_KEY
Parameters
| apiKey | apiKey |
Output
{"boxTypes":[[1,"PR"],[2,"Bell"],[3,"MagicSquare"]],"status":0}
Status code
| 0 | OK |
| 1 | Permission denied: wrong apiKey |
The first two box types are the Popescu-Rohrlich (PR, boxID=1) and the Bell (boxID=2) boxes. To create a box (i.e. invite a partner), the box type ID will be needed.
Inviting a partner to use a nonlocal box
- The inviter is always Alice, the invited partner will be Bob.
- We can invite another user on the basis of the other's user name.
- The box has a name to make it easy to remember.
GET https://nonlocalbox.wigner.hu/api/v1/invitePartner?apiKey=$ALICE_KEY&boxTypeID=1&inviteUserName=bob&boxName=ourFirstPRbox
Parameters
| apiKey | apiKey of the inviter |
| inviteUserName | username of the user to invite |
| boxTypeID | the type of box to create |
| boxName | the name of box to create |
Output
{"boxID":42,"status":0}
Status codes
| 0 | OK |
| 1 | Permission denied: wrong apiKey |
| 2 | Box quota exceeded |
| 3 | Invited user does not exist |
| 4 | Invalid box type |
Note: The API is not designed to do any communication, it is restricted to the emulation of the nonlocal box. The partner's notification on the invitation or any other necessary communication should be done with some other tool.
Using the box
Using the box as Alice
Use box ID 42 in transaction 2022021701 as Alice, sending x=0 as input:
GET https://nonlocalbox.wigner.hu/api/v1/useBox?apiKey=$APIKEY&boxID=42&transactionID=2022021701&x=0
Typical output:
{"a":0,"boxID":42,"status":0}
Using the box as Bob
Use box ID 42 in transaction 2022021701 as Bob, sending 1 as an input:
GET https://nonlocalbox.wigner.hu/api/v1/useBox?apiKey=$APIKEY&boxID=42&transactionID=2022021701&y=1
Typical output:
{"b":0,"boxID":42,"status":0}
Parameters
| apiKey | api key |
| boxID | ID of the box |
| transactionID | ID of the transaction |
| x | Alice input; either x or y is needed, cannot give both |
| y | Bob input; either x or y is needed, cannot give both |
Status codes
| 0 | OK |
| 1 | Permission denied to box, nonexistent box or wrong apiKey |
| 2 | Inconsistent data, the transaction completed before with different input |
| 3 | Invalid role. Alice gave y or Bob gave x |
- a
- the output of the box towards Alice
- b
- the output of the box towards Bob
List all boxes
This lists all the boxes where the given user is the inviter, i.e. Alice:
GET https://nonlocalbox.wigner.hu/api/v1/listBoxes?apiKey=$APIKEY
Typical output:
{"boxes":[{"aliceUser":"20","bobUser":"21","boxTypeID":"1","created":"2022-09-14 16:14:20","id":"4","name":"ourPRbox"}],"status":0}
Parameters
| apiKey | api key |
Status codes
| 0 | OK |
| 1 | Permission denied: wrong apiKey |
Note: boxes where the user is the invitee (i.e. plays the role of Bob) cannot be listed as it would enable the users to communicate using the API.