Back to Labs/Weave.
sm-labs01 Server API
Currently, there is a RESTy API at https://sm-labs01.mozilla.org:81/api/register/ that allows for remote account creation and password changes. Here is a brief description of how it works.
General
Only two types of HTTP requests are made at any point in time, a GET or a POST.
The server will return as a response an appropriate HTTP status code and the body will contain a comma-seperated list of numbers, whose meaning is described a little later. Generally, the status code and the body value is what you have to preserve to inspect.
Status Codes
400 Bad Request -- Will be returned if there was an error in the client's request. The numbers in the response body indicate what the errors were.
405 Method Not Allowed -- Trying to use GET where POST is to be used, and other such mismatches. No body.
201 Created -- Returned when an account as been successfully created. Body will contain a number to be interpreted as indicated in the table below.
417 Expectation Failed -- Returned when the client submitted all data correctly, except for the captcha elements. The response body will contain the HTML code required to display a new captcha.
200 OK -- Returned when the user's password was changed successfully. No body.
Account Creation
In order to avoid automated registrations, we use a two step process and incorporate a captcha. First, you need to perform a GET request at https://sm-labs01.mozilla.org:81/api/register/new/. This will return the HTML required to display a captcha to the user.
In the second step, you collect all the other information and make a POST request to the same address, with the following fields:
uid, password, mail, recaptcha_challenge_field, recaptcha_response_field
Of these, only 'mail' is optional. recaptcha_challenge_field and recaptcha_response_field are form fields that can be found in the HTML returned earlier.
Analyze the returned HTTP status code and body with the help of the table below and decide on the next course of action (Confirming to the user that the account was created, informing him that the username is already in use... etc.)
Changing Password
This requires a single POST to https://sm-labs01.mozilla.org:81/api/register/chpwd/ with the fields:
uid, password, new
HTTP 200 OK means the password was changed successfully. If you get a different status code, analyze the body with the help of the table below and decide on the next course of action.
Checking if userID/email already exists
Sometimes you may want to check is a particular userID or email already exists asynchronously. This requires a single GET request to https://sm-labs01.mozilla.org:81/api/register/check/<username> (Replacing <username> with desired username) or https://sm-labs01.mozilla.org:81/api/register/chkmail/<email> (Replacing <email> with desired email address)
Analyze the returned HTTP status code and body with the help of the table below and decide on the next course of action.
Body numeric codes and their meanings
| 3 | Account created (but no email address specified) |
| 2 | Account created and verification email sent |
| 1 | The requested userID/email is available |
| 0 | The requested userID/email is already in use |
| -1 | Client used a wrong HTTP method for the URL |
| -2 | Missing uid field |
| -3 | Invalid uid |
| -4 | Invalid mail |
| -5 | Account with given mail already exists |
| -6 | Missing recaptcha_challenge_field |
| -7 | Missing recaptcha_response_field |
| -8 | Missing password field |
| -9 | Internal server error |
| -10 | Server quota exceeded |
| -11 | Missing new field |
| -12 | Incorrect password |
The Sharing API
The sharing API allows the owning user of a folder to share it with other users, allowing them read-only access to it. Simply make a POST request to https://sm-labs01.mozilla.org:81/api/share/ and provide the following parameters:
uid, password, cmd
uid and password are the username and password of the user making the share request. cmd is a JSON object containing the following keys:
- version - This must be 1.
- directory - This is the directory to be shared, relative to the owner's user directory.
- share_to_users - This is a list of the users who should be given access to read the directory. If it is a list with "all" as its only element, then the directory is readable by anyone.
If successful, the response will be HTTP 200 OK with a body text of "OK". If the response code is different or the body is not "OK", then something has gone amiss. (Unfortunately, the sharing API wasn't designed with nearly as much attention to detail as the rest of the API; this will be changed in a later release--see bug 443931.)