Current Release

This documentation covers the latest release of Fedora CloudSync.

On this page:

Authentication

All API operations require authentication except GET serviceInfo and POST serviceInit.

Two forms of authentication are supported across the API:

  • Cookie-based Authentication. This will be used automatically if you use the REST API in a web browser, as when using the default CloudSync UI or manually testing the API. If you're not authenticated, you will be redirected to a page that prompts for your username and password.
  • HTTP Basic Authentication. This is intended for use by applications or scripts where cookie-based authentication is unsupported or difficult to implement.

Passwords in the Clear

With either form of authentication, credentials are sent over the network in a way that is trivial for attackers to intercept. Therefore, if traffic to the REST API is going over a public network, you are strongly advised to communicate with the service over HTTPS.

Authorization

All API operations can be invoked by any authenticated user except POST user, PATCH user, and DELETE user. The particular rules that apply to these operations are explained in their documentation below.

Supported Internet Media Types

Except where indicated otherwise, all operations in this API support two media types for request and response payloads:

  • JSON-based - The preferred format for Javascript and other lightweight clients.
  • XML-based - Useful in environments where XML tooling is the norm.

The exact media type used for a given operation depends on the type of data being sent or received. The #Formats section of this document provides a complete list of media types and their definitions.

Want to explore the API with your browser?

Most browsers won't natively show content in the custom XML and JSON-based media types defined by this API. But if you add .json or .xml to the URI, you can convince your browser to display the content because it will be delivered with a Content-Type header that your browser is more likely to recognize (application/json or application/xml). In addition, if the resource you're getting has links to other resources, those links will automatically have the .json or .xml appended to them.

For example, you might point your browser to https://example.org/cloudsync/api/rest/service.json and, if you have a JSON viewing plugin like JSON Formatter for Chrome or JSONView for Firefox, you can browse the API just by clicking links within the responses.

Supported HTTP Methods

This API uses the following methods for all operations:

  • When Creating or initializing resources, it uses POST.
  • When Reading resources, it uses GET.
  • When Updating resources, it uses PATCH.
  • When Deleting resources, it uses DELETE.

Does your client not support DELETE or PATCH?

Some HTTP clients have limited support for the less frequently used DELETE and PATCH methods. This API supports the X-HTTP-Method-Override header as a workaround to this problem. Issue a POST request and include this header, with a value of either DELETE or PATCH and the API will interpret your request as if it had been submitted with that method. If your client also lacks support for custom HTTP headers, you may use the _method=DELETE or _method=PATCH URL query parameter instead.

Javascript Client Library

The cloudsync-client.js library was written to support CloudSync's default user interface, and can be found at js/cloudsync-api.js in a deployed CloudSync instance. All operations documented below are supported through use of this library, which exposes the service using an RPC-style syntax.

  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.