The FotoWeb RESTful API is the recommended API for integrations with FotoWeb.
Uses of the API
The API can be used for the following purposes:
- Building custom user interfaces
- Building custom mobile apps
- Automating workflow
These are only examples. Any application that needs to read data from a FotoWeb server and maybe manipulate some of this data can make use of the FotoWeb API.
Introduction to HTTP and REST
An application using the FotoWeb RESTful API is called an API client. An API client communicates with the FotoWeb server by making HTTP requests, which roughly fall into two categories:
- Requests that only read data (GET requests)
- Requests that modify data on the server (POST, PUT, DELETE, PATCH, ... requests)
For every request, the server sends a response, which consists of a status code and (optionally) a body containing data. The status code is used for signaling whether a request was successful or what kind of failure has occurred. The FotoWeb REST API uses the standard HTTP status codes. Successful requests return either 200 OK or 204 No Content if the response does not contain a body. Client-side errors (invalid requests or authentication errors) are indicated by status codes 400-499 and server-side errors by status codes 500-599. The most important status codes are:
- 400 Bad Request (The request was malformed)
- 401 Unauthorized (The client did not provide valid credentials or no credentials at all, and the type of request requires authentication)
- 404 Not Found (The request URL does not refer to any existing resource)
- 500 Internal Server Error (The request is valid, but there was a problem on the server-side)
If the response body contains data, then it is usually in the JSON format (See http://www.json.org). Most programming languages these days have built-in support or mature third-party libraries for processing JSON data.
Sometimes, the client needs to send additional data to the server. This data is embedded in the request body. Here as well, JSON is used for most types of requests.
Resources and CRUD
Every request sent to the server has a URL (uniform resource locator), which refers to a resource. A resource can be any object known to the server and exposed by the API, such as an asset, an archive, an album or a user. Each resource has a unique URL, which is also its ID. API clients should not compose or decompose URLs. For example, it is not necessary to extract the numeric archive ID from the URL of an archive. Instead, the URL itself should be used as the ID of the archive.
An API client may read data from a resource (which is also called getting a representation of the resource), modify it, delete it, or create a new resource. These four operations are often referred to as CRUD (Create, Read, Update, Delete) operations. They typically use the following HTTP verbs:
- Create: POST or PUT
- Read: GET
- Update: PUT, PATCH or some custom methods such as PUBLISH
- Delete: DELETE
The PUT method accepts the URL or the resource, so when it is used to create a resource, the client defines the URL of the new resource. If it is used for updating a resource, the existing resource is replaced with the new one. PATCH, on the other hand, changes only part of an existing resource. POST requests are often made to collection resources to create a new item in the collection. A typical example is uploading assets to an archive, where the POST request is made to a folder in the archive, and the resources created are new assets in the archive.
The FotoWeb RESTfull API was designed to be as self-documenting as reasonably possible. When making GET requests, the API tells the client how to make progress and discover new resources. For example, when GETting the archive list, the FotoWeb RESTfull API returns the URLs of all accessible archives. Each of these URLs can then be used directly to request the respective archive. GETting an archive, in turn, returns URLs to assets and sub folders, and so on. Also, the URL of the archive list is returned as part of an API descriptor when making a GET request to an API entry point. Ultimately, an API client only needs to know the API entry point URLs in order to discover all other relevant URLs.
We strongly recommend using only URLs provided in responses to GET requests rather than hard-coded or composed URLs. This makes API client applications more resilient against future API changes and also more generic. For example, an application that lists assets in an archive can also be used for reading assets in a search result or an album or even in a future type of collection that is not defined in the current version of the API and FotoWeb thanks to hypermedia and URLs.
Getting started with the API
We recommend starting with the following topics:
Connecting to the API
To test the examples in this documentation or experiment with the API on your own, you have the following options:
- Write an API client in a programming language of your choice, such as Python or C#
- Use curl or a similar tool on the command line
- Use a browser extension such as Postman for Google Chrome
- Use the composer in Fiddler (Windows only) or a similar web debugging tool such as Charles (on Mac and Linux)
When using a browser extension, be aware that such extensions usually automatically send cookies stored by the browser. If you are logged in to FotoWeb in the same browser, this can cause the API to behave differently than expected, especially regarding authentication. To prevent this, you can explicitly send an empty
Cookie header, delete all cookies or configure the browser extension not to send any cookies, if possible.
When your own client, it is recommended to install a web debugging proxy such as Fiddler or Charles to inspect the HTTP requests, especially when using a HTTP client library that is built-in your language or platform or was developed by a third party.