37

Call the service API

To execute an action on collaboractor.com, you simply send an HTTP request to the address https://collaboractor.com/api/v1 followed by the name of the action and a series of parameters:

https://collaboractor.com/api/v1/action?login=abcdef&password=ABCDEF

You MUST use an HTTPS connection to insure that your identification code and your password, and implicitly, the files exchanged with the service, remain confidential. If you don't, the request returns an error HTTP 301 Moved Permanently. The certificate of the server was signed by Let's Encrypt.

action is subscription, upload, edit, download or delete, login and password are your identification code and your password. Depending on the action, the request is either a GET, POST or a DELETE and more parameters might be necessary.

Your identification code in 6 small letters is displayed in bold on your home page. To change your password, press the button in the menu bar to access the configuration of your account.

IMPORTANT: Check on the option REST  API in your user profile to authorize calling the API with your account. If you don't check on this option, the service returns the error HTTP/1.1 403 Forbidden.

Try entering https://collaboractor.com/api/v1/subscription?login=abcdef&password=ABCDEF in the address bar of your navigator replacing abcdef and ABCDEF by your identification code and your password.

IMPORTANT: Remember to clear the browser's history after testing a URL with your identification code and your password.

API

All calls to the API return either a HTTP error code such as HTTP/1.1 400 Bad Request, HTTP/1.1 401 Unauthorized, HTTP/1.1 403 Forbidden, HTTP/1.1 404 Not Found, HTTP/1.1 409 Conflict or HTTP/1.1 500 Internal Error or the code HTTP/1.1 200 OK with as content the representation in text/plain of a value or no content.

You can simply use a command like curl to call collaboractor.com.

$ curl -D - -X GET "https://collaboractor.com/api/v1/subscription?login=abcdef&password=ABCDEF"

Type the following command to clear the shell's history after testing a URL with your identification code and your password:

$ history -c

In a program, you will want a function able to send an HTTP request to a server and to collect the returned data. To run the examples in PHP, download the files sendhttp.php and filemimetype.php from the iZend library and copy them in the space of your own application.

The file sendhttp.php defines the functions sendget, sendpost and senddelete.

Read the page sendhttp of the documentation on iZend for more technical details.

sendget
sendpost
senddelete
SYNOPSIS

sendget($url, $args, $options=false, $header=false)

sendpost($url, $args, $files=false, $base64=false, $options=false, $header=false)

senddelete($url, $args, $options=false, $header=false)

DESCRIPTION

sendget sends a GET request to an HTTP server at the address specified by $url with the parameters in $args.

sendpost returns the document sent back by the HTTP service called with a POST at the address $url with the arguments $args and the attached $files encoded in base64 if $base64 is true.

senddelete sends a DELETE request to an HTTP server at the address specified by $url with the parameters in $args.

sendget, sendpost and senddelete accept a URL with parameters (query string) which must be escaped.

$url is a string of characters with the format https://collaboractor.com/api/v1/action where action designates the requested function such as subscription.

$args is an array containing the list of values of the parameters of the called function such as array( 'login' => 'abcdef', 'password' => 'ABCDEF', ... ). NOTE: The parameters in $args are automatically escaped.

$files contains the list of files attached to the request in the form of an associative array { 'docname' => {'name' => 'filename', 'type' => 'mimetype', 'tmp_name' => 'pathname'}, ... }. This parameter is optional. Typically, it's used to pass a file transmitted by an <input type="file" name="docname"... /> tag in an HTML form. If $base64 is true, the contents of the files are encoded in base64..

sendget, sendpost and senddelete return an array containing the HTTP code, the header and the body of the document returned by the server or false in case of error.

The file filemimetype.php defines the function file_mime_type.

Read the page file_mime_type of the documentation on iZend for more technical details.

file_mime_type
SYNOPSIS

file_mime_type($file, $encoding=true)

DESCRIPTION

file_mime_type returns the MIME type of the file $file; e.g. text/plain. If $encoding is true, file_mime_type adds the character encoding used for the data, e.g. text/plain; charset=utf-8. The MIME type and the encoding type are separated by a ; (SEMICOLON) followed by a space character (SPACE).

EXAMPLE

Assuming you have saved the file sendhttp.php in the current directory, run PHP in interactive mode, load the sendget function and call it with the URL https://collaboractor.com/api/v1/subscription and an array containing your identification code and your password in argument:

$ php -a
php > require_once 'sendhttp.php';
php > $r=sendget('https://collaboractor.com/api/v1/subscription', array('login' => 'abcdef', 'password' => 'ABCDEF'));
php > echo $r[0] == 200 ? $r[2] : 'HTTP ERROR ' . $r[0];
2023-12-31
php > quit
SEE ALSO

Check your subscription, Upload a document, Edit a document

Comments

Your comment:
[p] [b] [i] [u] [s] [quote] [pre] [br] [code] [url] [email] strip help 2000

Enter a maximum of 2000 characters.
Improve the presentation of your text with the following formatting tags:
[p]paragraph[/p], [b]bold[/b], [i]italics[/i], [u]underline[/u], [s]strike[/s], [quote]citation[/quote], [pre]as is[/pre], [br]line break,
[url]http://www.izend.org[/url], [url=http://www.izend.org]site[/url], [email]izend@izend.org[/email], [email=izend@izend.org]izend[/email],
[code]command[/code], [code=language]source code in c, java, php, html, javascript, xml, css, sql, bash, dos, make, etc.[/code].