Universal API WIP
Contents
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
/apiendpoint, 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
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
siteengine:/site/<site-path>/_/<app-name>/<api-name>/ -
For
webappengine:(/webapp/<app-name>/_/<app-name>/<api-name>/ -
For
adminengine:/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>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.
Widget API
Widget API provide the way to dynamically extend Admin UI.
API discovery
GET :8080/api - returns JSON with a list of all available APIs in the system.
apiUrl()
To safely generate an API URL, use the apiUrl() function that is part of the Portal Library.
| When invoked, the function will generate a contextual service url based on the context of the current controller. |
Reserved API application names
Applications names without namespace are reserved. This list includes, but not limited to, the following:
-
media -
admin -
component -
attachment -
image -
asset -
service -
error -
idprovider
