Table of Contents
Introduction to Representations and Media Types
31. March 2025
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 the 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, which contains information about all archives.
Please note: In demonstrations of the API, API requests are sometimes sent from browsers by appending .json to an URL. This is an unofficial and unsupported feature that must not be used in production code. Please do not attempt this alternative if you are experiencing problems with the API. Please 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 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 which are sent to the API and which make changes to resources on a FotoWeb site require additional data in the body of the request. For example, a request which updates metadata of an asset must contain 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 which 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 what the request does.
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 for GET requests), the API documentation describes 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.