Universal API WIP

Universal API enables mounting of http controllers safely made available on /api endpoint as well as within an application (or site’s) URL space, without the use of routers. It supports Headless approach or Site engine, Webapp engine and Admin engine needs to access dynamic data, like REST API, GraphQL API, or other data sources.

The Main Features of Universal API are:

Secure be default
- APIs are not mounted anywhere by default, so you don’t need to worry about accidental exposure of an admin API on a site.
- Nobody can access an API without explicitly specifying access rights in the descriptor.
- Cache pollution is avoided by mounting APIs to a single endpoint (per engine).
Headless friendly. APIs can be mounted on /api endpoint, so they can be used by any client.
Granular. Mounting of API must be explicitly specified in engine descriptor files.
Modular. APIs can be borrowed from other applications, so you can use existing APIs in your application.

Controller

To create an API, place an http controller file in the src/main/resources/apis/ structure of your project. Each controller needs to be placed in a folder matching its name i.e.: src/main/resources/api/myapi/myapi.js

Example service controller

src/main/resources/apis/<api-name>/<api-name>.js

exports.get = function(req) {
  return {
    body: {
      time: new Date()
    },
    contentType: 'application/json; charset=utf-8'
  };
};

Descriptor

API descriptor is required. It provides a way to define the API’s access, availability on /api endpoint as well as display name, description and documentation URL.

Example of Full API descriptor:

<api>
  <mount>true</mount> (1)
  <display-name>My API</display-name> (2)
  <description>API for My App</description> (3)
  <documentation-url>https://developer.enonic.com/docs/api</documentation-url> (4)
  <allow> (5)
    <principal>role:system.admin</principal>
    <principal>role:myapp.myrole</principal>
  </allow>
</api>

1	By default, APIs are not mounted on the Generic API endpoint. To enable it, `<mount>true</mount>` should be set in the descriptor.
2	display-name is the name of the API that will be shown in the UI.
3	description is a short description of the API that will be shown in the UI.
4	documentation-url is a link to the API documentation that will be shown in the UI.
5	APIs must list principles that have access to it. It is required to specify at least one principal. Use `role:system.everyone` to make the API public.

Endpoint

API mount is context-aware:

Generic API endpoint /api/<app-name>/<api-name>/
For site engine: /site/<site-path>/_/<app-name>/<api-name>/
For webapp engine: (/webapp/<app-name>/_/<app-name>/<api-name>/
For admin engine: /admin/_/<app-name>/<api-name>/

Engine descriptors need to specify the available API names in the api element, while Generic API endpoint can be disabled in API Descriptor itself.

Example site descriptor with mounting of self-contained and external APIs:

<site xmlns="urn:enonic:xp:model:1.0">
  <apis>
        <api>ws</api>
        <api>app:graphql</api>
  </apis>
  <form/>
</site>

Built-in APIs

Media APIs

The Media APIs is a built-in API that provides access to media files in CMS repositories.

Media Image API is available real-time processing and delivery of rasterized RGB/RGBa image media.

Media Attachment API gives access to Content attached binaries - like PDFs, Word documents, etc.

These two APIs are always mounted on Generic Endpoint as well as on Sites. Admin Tools and Webapps can also mount them by specifying them in the api element of the engine descriptor.

media
admin
component
attachment
image
asset
service
error
idprovider

Universal API WIP

Contents

Controller

Descriptor

Endpoint

Built-in APIs

Media APIs

Widget API

API discovery

apiUrl()

Reserved API application names

Contents

Contents