Introduction

In Wedia, the DAM can be setup in very precise ways, and to reflect this setup, each Wedia server is serving an updated to this setup Swagger documentation : https://wedia server/api/rest/doc/dam

The Wedia API rendered using ReDoc

If you don’t have a Wedia server yet, you may browse our demo documentation here : https://club-wed.wedia-group.com/api/rest/doc/dam

This API documentation (OpenAPI Specification) can be rendered either under Swagger UI or under ReDoc.

The rendering type defaults to ReDoc, but you can ask your Wedia Account Manager to change it to Swagger.

The API has been divided in multiple entry point, and you will be offered a menu to select the type of API services you will browse :

Type of service	Default URI (here to club-wed server for example)

Type of service	Default URI (here to club-wed server for example)
DAM services	https://club-wed.wedia-group.com/api/rest/doc/dam
Restful data services	https://club-wed.wedia-group.com/api/rest/doc/data
Media services	https://club-wed.wedia-group.com/api/rest/doc/media
JSon services (legacy deprecated services)	https://club-wed.wedia-group.com/api/rest/doc/json

Retrieve a specific rendering

You can specify the filename to get a specific rendering or the OAS file (JSon). The name of the OAS file is swagger.json. By example:

https://club-wed.wedia-group.com/api/rest/doc/dam/swagger.json

Swagger UI

To get the documentation rendered by Swagger UI, specify the suffix ui. By example:

https://club-wed.wedia-group.com/api/rest/doc/dam/swagger.ui

ReDoc

To get the documentation rendered by ReDoc, specify the suffix redoc. By example:

https://club-wed.wedia-group.com/api/rest/doc/dam/swagger.redoc

Documentation portal

You can access all the documentation via the backoffice administration page:

https://club-wed.wedia-group.com/_plugins/WXM_RESTAPI/page/admin/apidoc/apidocmenu.jspz

Or via the administration backoffice page “API Services” https://club-wed.wedia-group.com/admin/api:

Service	Class	URI

Service	Class	URI
Dam services	com.noheto.apirest.resturl.RestDamService	https://club-wed.wedia-group.com/api/rest/dam?export=redoc
RESTful services	com.noheto.apirest.resturl.RestDataService	https://club-wed.wedia-group.com/api/rest/data?export=redoc
All CRUD API (Portal)	com.noheto.apirest.resturl.RestUrlService	https://club-wed.wedia-group.com/api/rest?export=redoc

The following sections are only applicable to Wedia Account Managers. Feel free to skip them as they explain how to set up properly the documentation portal for a Wedia DAM.

Performance of the documentation display

(Since 2022.1) With the increase in the number of services and their documentation, the OAS3 file used for display increases in size and becomes not only longer to generate, load and especially transformed into DOM by the renders we use, especially ReDoc. In order to make the rendering and display of the API documentation faster, a new display system has been implemented.

This new system is based on a filter system:

filtering by tag
filtering of the information part of the document

The old display system using ReDoc or Swagger pages directly is refered to as Version 1. The new system is referred to as Version 2.

Other settings have been set up for technical adjustments (especially regarding file uploads) that have default settings that should work in the general case. In case specific cases arise, contact @Joël DRIGO for possible testing of different configurations.

Filter information chapters

apiDocInfoExcluded

This parameter allows you to indicate which chapters of the information part you do not want to include in the documentation files. It is an array of strings. Any other value will be ignored.

Here is the list of existing sections:

infos/description.GENERALPARAMS: general syntax of the parameters
infos/description.ERRORS: documentation on error messages
infos/description.FILTERS: the documentation of the query language (JSONQuery)
infos/description.IMAGING: documentation of the syntax of image transformations
infos/description.DEBUG: documentation of the debug parameter
infos/description.SECURITY: security documentation (not currently deployed)

You can comment a value by starting it with // followed by a space.

Here is a configuration (without exclusion) that can be used as a template (uncomment the chapter identifiers to exclude from the documentation):

[
   "// infos/description.GENERALPARAMS",
   "// infos/description.ERRORS",
   "// infos/description.FILTERS",
   "// infos/description.IMAGING",
   "// infos/description.DEBUG",
   "// infos/description.SECURITY"
]

Configure tags

apiDocPortal

This is a json that describes the display of the documentations. All properties are optional. The default configuration enables version 2 on dam services, and version 1 on the others, with the standard tag group selection.

At the root, we find the default configuration of all types of services, and the specific configurations of each type of service, namely the following properties:

version: a number, the version to display (default is 1)
tags: an array of strings, the list of tags (in the display order) if you want another configuration than the default one
Unknown groups are ignored. If the list contains no groups, the default list will be used.
dam: a JSON object, the specific configuration of the dam services
data: a JSON object, the specific configuration of the data services
json: a JSON object, the specific configuration of the json services
media: a JSON object, the specific configuration of the media services

For each type of service, we can find the specific properties version and tags.

For example:

{
    "dam": {
        "version": 2,
        "tags": [
            "assets",
            "read",
            "list",
            "search",
            "createmodify",
            "delete",
            "workflows",
            "user",
            "errors",
            "confluence"
        ]
    }
}

Services

The Rest API documentation is currently organized into four types of services:

dam: Documentation of DAM services (automatically generated).
data: Documentation of CRUD services
json: Documentation of legacy services
media: Documentation of legacy imaging services

Tag groups

Tags are grouped into tag groups. The configuration of the documentation of a service type lists the groups of tags that will be displayed in the documentation homepage: for each group of tags, the sub-section corresponding to the tags of this group will be displayed. It is possible to control the division of the global documentation of a service type into more or less sub-documentation

Some tags are present in several tag groups. In order to avoid redundancy of the same end points in several sub-documents, the tag groups are hierarchical. Thus, if a tag group has a parent tag group in the tag group selection, it will not be displayed in the home page.

Here are the tag groups by service type (this list is also the default tag list (tags that have a parent are automatically deleted):

dam
- assets
  - tags: assets, damobjects
  - parents: none
- get
  - tags: search, read
  - parents: none
- read
  - tags: readbyid
  - parents: get
- list
  - tags: readlist
  - parents: get
- search
  - tags: search
  - parents: get
- createmodifydelete
  - tags: create, modify, delete
  - parents: none
- createmodify
  - tags: create, modify
  - parents: createmodifydelete
- create
  - tags: create
  - parents: createmodify
- modify:
  - tags: modify
  - parents: createmodify
- delete:
  - tags: delete
  - parents: createmodifydelete
- workflows:
  - tags: workflows
  - parents: none
- user
  - tags: user
  - parents: none
data
- get
  - tags: search, read
  - parents: none
- read
  - tags: readbyid
  - parents: get
- list
  - tags: readlist
  - parents: get
- search
  - tags: search
  - parents: get
- createmodifydelete
  - tags: create, modify, delete
  - parents: none
- createmodify
  - tags: create, modify
  - parents: createmodifydelete
- create
  - tags: create
  - parents: createmodify
- modify:
  - tags: modify
  - parents: createmodify
- delete:
  - tags: delete
  - parents: createmodifydelete
- workflows:
  - tags: workflows
  - parents: none
- user
  - tags: user
  - parents: none
json
- get
  - tags: view, tree, collections, resource
  - parents: none
- read
  - tags: view, tree, collections
  - parents: get
- images
  - tags: resource, imaging
  - parents: get, imaging
- resource
  - tags: resource
  - parents: get, images
- imaging
  - tags: imaging
  - parents: none
- createmodifydelete
  - tags: create, update, updateorcreate, delete, lock
  - parents: none
- createmodify
  - tags: create, update, updateorcreate, lock
  - parents: createmodifydelete
- create
  - tags: create
  - parents: createmodify
- update
  - tags: update, lock
  - parents: createmodify
- updateorcreate
  - tags: updateorcreate, lock
  - parents: createmodify
- delete
  - tags: delete
  - parents: createmodifydelete
- workflows
  - tags: workflows
  - parents: none
- user
  - tags: user
  - parents: none
media
- no group tags

Special tag groups

These are tag groups that do not contain tags from the OAS documentation directly.

errors: a link to the error documentation
confluence: a link to the confluence documentation of the REST API

Configure the download

apiDocOasStream

This is a json object that determines the configuration of an OAS file download.

Its properties (all optional) are:

streamType: the default stream type (used for UTF-8)
The default value is BCT.
The possible values are:
- CT, Use CTFile, without buffer to write to servlet stream.
- BCT, Use CTFile, with buffer to write to servlet stream
- PW, Use a PrintWriter to write to servlet stream and a FileReader to read the file
- BPW, Use a PrintWriter to write to servlet stream and nio to read the file
- NIO, Use java.nio
- AIO, Use Apache IOUtils
altStreamType: the alternate stream type (used for a charset other than UTF-8)
The default value is BPW.
bufferSize: the default buffer size

This is a number of bytes, or a number of kibibytes in the form <n>K. The default value is 65536 (64K).

inputBufferSize: the size of the buffer used to read the file if it is configurable
The default value is that of bufferSize.
outputBufferSize: the size of the buffer used for writing to the servlet stream if it is configurable
The default value is that of bufferSize.
etag: a boolean (default is true), activates the ETag
gate: a boolean (default is false), activate the stopwatches

Direct access

This new way of displaying documentation uses the same URIs as the old system. The only difference is that the documentation is displayed differently.
It is possible to display (or retrieve the file) according to the old mode, if the new mode is activated (i.e. to access version 1 if version 2 is activated): just add v1 in the URL parameters. By example:

https://club-wed.wedia-group.com/api/rest/doc/dam?v1

To display directly the documentation of a tag group, add the tag parameter with the value of the tag group identifier:

https://club-wed.wedia-group.com/api/rest/doc/dam?tag=create

It is of course always possible to display the alternative rendering to the one configured by default in the same way as shown here: Redoc Swagger API Documentation | Retrieve a specific rendering). For example, if the default rendering is ReDoc, the following url allows a Swagger UI rendering:

https://club-wed.wedia-group.com/api/rest/doc/dam/swagger.ui

Securing access

Access to these documentations is limited by default to the following roles (on a technical backoffice account):

Administrators
Developer
ApiOperators
ApiWatchers
ApiTesters 11.29
Watchers

You can disable this security by configuring the plugin with the apiDocSecure parameter (Not recommended).

Standalone documentation

See Tip - Export API documentation to a standalone HTML (ReDoc rendering)

Access to documentation by user (object user)

11.29

API documentations can be accessed by a user via a special portal secured by a security rule allowing to test user properties (role, dedicated property, etc). The URL of this portal is /api/rest/docportal(example: https://club-wed.wedia-group.com/api/rest/docportal).

2021.6 The domain restapi_docportal is included in the release (See Upgrading to 2021.6 | The release now integrates the domains and actions of security , or https://crossmedia.atlassian.net/browse/WXM-10689 ).

The portal is accessible :

to all users if security is not enabled
to no user if security is enabled and the restapi_docportal domain does not exist or it isn’t activated
to all users if security is enabled and the restapi_docportal domain exists and is activated, but the access action does not exist or is not enabled
to users who validate the rules if security is enabled and the restapi_docportal domain exists and is activated, and the access action exists and is activated

The URLs of the different documentations are slightly different from those of the portal accessible in back-office administration access.

Type of service	URI (here to club-wed server for example)

Type of service	URI (here to club-wed server for example)
DAM services	https://club-wed.wedia-group.com/api/rest/docportal/dam
Restful data services	https://club-wed.wedia-group.com/api/rest/docportal/data
Media services	https://club-wed.wedia-group.com/api/rest/docportal/media
JSon services (legacy deprecated services)	https://club-wed.wedia-group.com/api/rest/docportal/json

The Error Documentation Page is also accessible in this portal, with the URL https://club-wed.wedia-group.com/api/rest/docportal/errors.

Security action

Domain name

restapi_docportal

Action name

access

Parameters

request
surfer