Table of Contents
Introduction to Representations and Media Types
09. March 2026
Table of Contents
Resources and Representations
Clients of the FotoWeb RESTful API can extract data from a FotoWeb system by requesting representations of resources.
A resource can be, for example, an asset, a collection (such as an archive or album), or a list of archives on the site. Each resource has a distinct URL.
A representation of a resource is a document of a certain media type, such as HTML or JSON. The FotoWeb REST API defines multiple JSON-based media types. Each resource can have one or more representations and at most one representation of each media type.
How to request a Representation
In order to request a representation, an API client sends a GET request to the URL of the resource. The representation is selected by specifying the media type in the HTTP Accept header:
GET <URL of resource> Accept: <media type>
Example:
GET /fotoweb/archives/ Accept: application/vnd.fotoware.collectionlist+json
In this example, the client requests a representation of the media type application/vnd.fotoware.collectionlist+json from the resource with the URL /fotoweb/archives. The resource is the list of archives on the FotoWeb site, and the requested representation is a JSON document, that contains information about all archives.
Note
In demonstrations of the API, API requests are sometimes sent from browsers by appending .json to a URL. This is an unofficial and unsupported feature that must not be used in production code. Do not attempt this alternative if you are experiencing problems with the API. Do not use this method when submitting a dump of an API request to a support ticket.
If the request for a representation was successful, the server sends a response with status 200 OK, which contains the requested representation in the body. Furthermore, the HTTP Content-Type header contains the name of the media type of the representation:
200 OK Content-Type: <media type> <body>
Example:
200 OK
Content-Type: application/vnd.fotoware.collectionlist+json
{ "data": [...], "paging": {...} }
In this example, the server returned the requested representation of the media type application/vnd.fotoware.collectionlist+json, which is a JSON document containing a data attribute and a paging attribute.
What representations are available?
For each resource, the API documentation describes which representations (media types) are available.
Request Body types
Some requests sent to the API that modify resources on a FotoWeb site require additional data in the request body. For example, a request to update an asset's metadata must include the metadata in the request body. Similar to resource representations, FotoWeb uses JSON as the underlying data format for request body data and defines multiple formats that have different media types.
How to send a Request Body
When sending a request with a request body, an API client must set the HTTP Content-Type header to the name of the media type of the document which is sent in the request body:
<method> <url> Content-Type: <media type> <body>
Example:
PATCH /fotoweb/archives/5000-Incoming/2015/06/06/DSC0123.JPG
Content-Type: application/vnd.fotoware.assetupdate+json
{ "metadata": { ... } }
In this example, the API client sends a PATCH request to the resource with the given URL with a body of media type application/vnd.fotoware.assetupdate+json. The request body is a JSON document with a metadata attribute.
If the request is successful, then the server might send a response of 204 No Content or 201 Created or something else, depending on the request.
How to send and receive data in one request
If the response is expected to contain a body, then the request must also contain an Accept header:
<method> <url> Content-Type: <media type in request> Accept: <expected media type in response> <request body>
The server will respond to such a request with 200 OK, a Content-Type header and the requested response body:
200 OK Content-Type: <actual media type in response> <response body>
What media types can be used with a Request?
For every request (except GET), the API documentation specifies which media type (if any) must be sent in the request body and which media type (if any) is returned in the response body. A GET request never has a request body, and the response body is always a resource representation.