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.