Table of Contents

MIME Type Example Attributes Methods GET POST (create user) Synchronizing Users from Custom Authentication Providers

User List Representation

This article describes the JSON format that represents a list of users in the Users and Groups API.

12. May 2025

Table of Contents

MIME Type Example Attributes Methods GET POST (create user) Synchronizing Users from Custom Authentication Providers

MIME Type

application/vnd.fotoware.user-list+json

Example

1

2

3

4

5

6

7

8

9

{

data: [...],

paging: { // can be null

next: "...", // can be null

prev: "...", // can be null

first: "...",

last: "..."

}

Attributes

Name	Type	Description
data	Array of user representations	Contains all users which are in this part of the user list. The format of each item is the same as the user representation of a single user.
paging	Paging information (object)	Paging information. For more information, see Paging. If the list has only one page, then this field is null.
paging.next	URL (string), links to UserList	Link to the next page of the list. If the current page is the last page, then this link is null.
paging.prev	URL (string), links to UserList	Link to the previous page of the list. If the current page is the first page, then this link is null.
paging.first	URL (string), links to UserList	Link to the first page of the list. This is never null.
paging.last	URL (string), links to UserList	Link to the last page of the list. This is never null.

Methods

The following HTTP verbs are allowed on user lists:

GET

GET href
Accept: application/vnd.fotoware.user-list+json

Read user list. Returns the representation described above.

POST (create user)

POST href
Content-Type: application/vnd.fotoware.user+json
{...}

Creates a new user. This request is only allowed on the global user list and only on the first page.

The request body MUST be a User representation, but fields can be omitted. Fields that are not defined in the request body will be set to default values.

Some fields MUST NOT be defined. See the remarks section of the User documentation for details.

The following fields MUST be defined:

username
address.firstName
account.email

If successful, the server sends the following response:

201 Created
Location: new_user_url

Where new_user_url is the URL of the new user, which has a User representation.

Synchronizing Users from Custom Authentication Providers

If the request body contains at an entry in the externalIDs array, then the user is synchronized from a custom authentication provider. This means that the request behaves differently in the following ways:

If a user exists which has the same external user ID for the same provider ID, then instead of creating a new user, FotoWeb will update this existing user.
All fields that are present in the request body will be updated. Unlike a PATCH request to a user, the memberships array may be present, and all group memberships of the existing user will be replaced by the new ones.
Either way, the server always returns 201 Created with the user URL. To see if the user has been updated rather than created, request the user data (as shown below) and check if the modified and created fields are different.

To get the complete user data of the updated (or created user) in the response, add the following header to the POST request above:

Accept: application/vnd.fotoware.user+json

The server then returns

201 Created
Location: new_user_url
Content-Type: application/vnd.fotoware.user+json
{...}

with a full User representation in the response body.