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 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 typeapplication/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-ServerX-Powered-ByServer.

  • 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.

  • Was this article helpful?