Skip to main content
Documentation & User Guides | FotoWare

API Entry Points

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.

  • Was this article helpful?