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 that 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: public and 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 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

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

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

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 hostname with the hostname 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 hostname 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, that 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/"
  }

Name	Type	Description
`server`	string	Human-readable short description of the server. The content of this property is unspecified and should not be used programmatically. It can be shown in user interfaces. Changing or hiding this heading is the system administrator's responsibility. They can do this using a registry change or outbound URL rewrite rules. They can also set up a reverse proxy (such as NGINX) or a web application firewall (WAF) to override this header. FotoWeb functionality does not depend on this header.
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 that 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 that are shared using show on homepage.

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/",
  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 the 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 to which assets can be uploaded. See ingestion for more details.
`copy_to`	URL (links to collection list)	URL of list of collections to which assets can be copied. See ingestion for more details.
`move_to`	URL (links to collection list)	URL of list of collections 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 common to both API descriptor types.

Removing unwanted response headers

The following response headers may reveal information about the FotoWeb server and related components, such as the web server, so FotoWeb On-Premises administrators may want to suppress or override them for security reasons: FotoWeb-Server, X-Powered-By, Server.

FotoWeb-Server: This header is sent directly by FotoWeb and will be removed in a future release. Administrators can suppress or override this header using IIS settings or a reverse proxy.
X-Powered-By: This header is sent directly by FotoWeb and will be removed in a future release. Currently, it contains the FotoWeb version. After removal, it will contain ASP.NET, which is the default value sent by IIS. It can be changed in IIS settings, either on the global or website level, or by using a reverse proxy.
Server: This header is sent by IIS and contains the IIS version. It can be suppressed or overridden using a reverse proxy, an outbound URL rewrite rule, or a registry setting. For more information, see IIS documentation or get assistance from Microsoft.

Changing or suppressing any of these headers has no impact on FotoWeb functionality but may impact legacy integrations with FotoWeb. Note that none of these headers is documented by Fotoware, so integrators are discouraged from using them. If you are using an integration that relies on any of these headers, you can use IIS settings or a reverse proxy to temporarily set these headers as required by the integration. In the long run, we recommend updating integrations to not rely on these headers. To programmatically detect if FotoWeb is running on some domain, make a request to the /fotoweb/ API endpoint instead.