Gambas Documentation - /doc/farmproto

/doc/farmproto

# Gambas Farm Server Protocol

## Index

- 1. Protocol summary

- 2. Register a user

- 3. Confirm registration

- 4. Publishing a software

- 5. Get information about a software

- 6. Download a software

- 7. Add or remove a vote for a software

- 8. Software search

- 9. Tag search

- 10. Error codes

## 1. Protocol summary

The Gambas farm server protocol is based on HTTP requests.

### Sending a request

Most of the requests must me submitted through the POST action, exactly like a HTML form.

Gambas 3.7 will provide an HttpForm class to send these kind of requests easily.

If you don't have to send files, you can use the GET action.

### Getting the answer

The answer is usually a text file whose the first line is the answer status, and the rest of the file the answer contents.

The line separator is the `CR`+`LF` sequence.

If the status line is `10 OK`, then the request has been successful, and the useful contents starts at the second line.

Otherwise, the request has failed, and the answer status is made of a two-digit error code, a space, and an error description. The answer contents may include more error details.

Every text is UTF-8 encoded.

## 2. Register a user

### Request

    http://<server>/farm/register

### Arguments

`login` | User login.
`password` | User password.
`name` | User full name.
`email` | Confirmation e-mail.

### Description

This request allows to register a new user to the server.

An mail is sent to the specified e-mail address that includes an activation link. That activation link is the confirm registration request (see the next paragraph), and is based on a random hexadecimal key.

## 3. Confirm registration

### Request

    http://<server>/farm/confirm

### Arguments

`login` | User login.
`key` | Confirmation key.

### Description

This request confirm the registration of the new user.

The confirmation key must match the key provided into the e-mail sent by the registration request.

## 4. Publishing a software

### Request

    http://<server>/farm/publish

### Arguments

`login` | Software owner login.
`password` | Software owner password.
`name` | Software name.
`version` | Software version, with the X.Y.Z syntax.
`desc` | Software full description.
`gambas` | Gambas version required, with the X.Y.Z syntax.
`checksum` | SHA256 source archive checksum.
`source` | Source archive. It must be a file with the `tar.gz` or `tar.bz2` extension.
`icon` | Software icon. It must be a 64x64 `PNG` file.
`screenshot` | An optional screenshot of the software. It should be a `JPEG` or `PNG` file.
`url` | An optional URL for the software project website.
`tags` | A list of tags, as identifiers separated by commas.
`dependencies` | A list of dependencies separated by commas. A dependency is a software name followed by an optional minimum `X.Y.Z` version.

### Description

This request allows to register a software to the server.

You must provide a valid login and password to register.

## 5. Get information about a software

## 6. Download a software

## 7. Add or remove a vote for a software

## 8. Software search

## 9. Tag search

## 10. Error codes