API Entry Points

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

The API entry points are the only parts of the API with well-known URLs. They provide API descriptors which contain information about the API, the available functionality, and the URLs to access it.

Usually, the first thing an integration does when accessing FotoWeb through the API is to request an API descriptor from one of the API entry points.

The entry point can be seen as the "home page" of the API with "links" to all the available resources.

Public vs. Private Entry Point

There are two main entry points for the FotoWeb API, one public and one private.

The Public entry point is for unauthenticated, read-only guest access, and is only available if guest access is enabled and licensed on the FotoWeb server.

The Private entry point allows authenticated access to the server to view and modify data. It requires authentication, either as administrator (server-to-server authentication) or as a specific user.

Entry points
Public entry point	`/fotoweb/`
Private entry point	`/fotoweb/me/`

Which entry point should be used?

Here are some examples of which entry points should be used in different scenarios. Remember that using the public entry point requires a portal license that enables guest access:

Creating a public portal with a custom user interface: Use public entry point
Creating a portal with user logon: Use private entry point with user authentication
Integration with access to all assets on the site: Use private entry point with server-to-server authentication
Integration with access to albums of a specific user: Use private entry point with user authentication
Automated ingestion of assets: Use private entry point
Automated export of assets from public archives: Use public entry point
Automated export of assets: Use private entry point

Syntax

Use the following requests to access the public and private entry point:

Note: Before proceeding, see Introduction to Representations and Media Types.

Public entry point

GET /fotoweb/
Accept: application/vnd.fotoware.api-descriptor+json

The following cURL command requests the public entry point. Remember to replace the host name with the host name of your site:

curl \
  --header "Accept: application/vnd.fotoware.api-descriptor+json" \
  http://fotoweb.acme.com/fotoweb/

Private entry point

GET /fotoweb/me/
Accept: application/vnd.fotoware.full-api-descriptor+json
authentication headers

The following cURL command requests the private entry point. Remember to replace the host name and the API key with the proper values for your site:

curl \
  --header "Accept: application/vnd.fotoware.full-api-descriptor+json" \
  --header Authorization: Bearer ACCESS_TOKEN \
  http://fotoweb.acme.com/fotoweb/me/

API descriptors

The only representation of an entry point is an API descriptor. This is a JSON document, returned in the response body, which contains information about the API.

The representation of the public entry point is the public API descriptor.

The representation of the private entry point is called the full API descriptor.

Public API descriptor

MIME type: application/vnd.fotoware.api-descriptor+json

The public API descriptor contains information about the public FotoWeb API:

{
  server: "FotoWeb Core",
  searchURL: "/fotoweb/archives/{?q}"
  archives: "/fotoweb/archives/",
  albums: "/fotoweb/albums/",
  taxonomies: "/fotoweb/taxonomies/"
}

Name	Type	Description
`server`	string	Human-readable string describing the server type and license
searchURL	URL (links to collection list)	URL template for global searches in all collections on the site. By replacing the placeholders in the template with search parameters, a client can search in all collections.
`archives`	URL (links to collection list)	URL of the archive list of the site. This list contains only archives which are accessible by the guest user.
`albums`	URL (links to collection list)	URL of the public album list of the site. This list contains albums which are shared using show on homepage.
`taxonomies`	URL (links to taxonomy list)	URL of the list of all taxonomies on the site

Full API descriptor

MIME type: application/vnd.fotoware.full-api-descriptor+json

The full API descriptor contains extended information about the private FotoWeb API. Its contents may vary depending on whether server-to-server or user authentication is used and which user is accessing the API.

{
  server: "FotoWeb Core",
  href: "/fotoweb/me",
  searchURL: "/fotoweb/archives/{?q}"
  archives: "/fotoweb/me/archives/",
  albums: "/fotoweb/me/albums/",
  albums_own: "/fotoweb/me/albums/mine/",
  albums_shared: "/fotoweb/me/albums/shared-with-me/",
  albums_archived: "/fotoweb/me/albums/archived/",
  albums_deleted: "/fotoweb/me/albums/deleted/",
  copy_to: "/fotoweb/me/copy-to/",
  move_to: "/fotoweb/me/move-to/",
  upload_to: "/fotoweb/me/upload-to/",
  taxonomies: "/fotoweb/taxonomies/",
  widgets: {
    selection: "/fotoweb/widgets/selection"
  },
  user: 
  {
    href: "/fotoweb/users/jsmith",
    userName: "jsmith",
    fullName: "John Smith",
    firstName: "John",
    lastName: "Smith",
    userId: 15002,
  },
  permissions: {
    delegateDownload: true,
    allowTaxonomyEditing: true,
    createAlbums: true
  }
}

Name	Type	Description
`archives`	URL (links to collection list)	URL of the list of archives that the current user can access. If server-to-server authentication is used, then this list contains all archives on the site.
`albums`	URL (links to collection list)	URL of the list of albums accessible by current user. This list contains all albums that the user can access.
`albums_own`	URL (links to collection list)	URL of the list of albums owned by the current user.
`albums_shared`	URL (links to collection list)	URL of the list of albums shared with the current user.
`albums_archived`	URL (links to collection list)	URL of the list of archived albums owned by the current user.
`albums_deleted`	URL (links to collection list)	URL of the list of deleted albums owned by the current user.
`upload_to`	URL (links to collection list)	URL of list of collections which to which assets can be uploaded. See ingestion for more details.
`copy_to`	URL (links to collection list)	URL of list of collections which to which assets can be copied. See ingestion for more details.
`move_to`	URL (links to collection list)	URL of list of collections which to which assets can be moved. See ingestion for more details.
`widgets.selection`	URL (links to HTML page)	URL of the selection widget for CMS integration
`user.href`	URL (links to user)	URL of the user that the client is authenticated as
`user.userName`	string	User name of the user that the client is authenticated as
`user.fullName`	string	Full name of the user that the client is authenticated as
`user.firstName`	string	First name of the user that the client is authenticated as
`user.lastName`	string	Last name of the user that the client is authenticated as
`user.userId`	integer	ID of the user that the client is authenticated as
`permissions.delegateDownload`	boolean	User has permission to share an album with download permissions
`permissions.allowTaxonomyEditing`	boolean	User has permission to modify taxonomies
`permissions.createAlbums`	boolean	User has permission to create albums
searchURL	URL (links to collection list)	URL template for global searches in all collections on the site. By replacing the placeholders in the template with search parameters, a client can search in all collections.

See also documentation of the public API descriptor for fields which are common to both API descriptor types.