Lesson 11.1: The REST API at a glance
Apps, other sites and scripts talk to Exponential through its REST interface. Before learners call it (lesson 11.2) or extend it (lesson 11.3), they need the map: which extension serves what, which routes answer at which version, and which settings decide how it behaves.
At a glance
| Course | Developers |
| Module | Module 11: The REST API |
| Duration | 40 minutes (20 presenting, 20 exercise) |
| Level | Intermediate |
| Audience | Developers |
| Prerequisites | Module 8 |
Learning objectives
After this lesson, learners can:
- name the kernel's REST framework, the
ezprestapiextension and what each serves; - read a route:
/api/<prefix>/<version>/<path>; - tell which routes answer at v1 and v2, and that writes answer at v2 only;
- explain that every call checks the user's content policies;
- find and read the REST settings with
exp:ini.
Trainer's notes
How to present it
Source: REST API v1 and v2: one extension.
- What serves what (5 minutes). The REST framework is in the kernel (
kernel/private/rest/,settings/rest.ini); the content routes come from the extensionezprestapi, whose providerezp7xRestApiProviderserves the prefixesezpandezpl; the kernel'sezpRestAuthProviderservesauth(the OAuth2 token endpoint).ezprestapiprovideris deprecated. - An address (3 minutes).
/api/ezp/v1/content/node/2:ApiPrefix/api, prefixezp, versionv1, path/content/node/2. - The routes (5 minutes). Project the table of section 2 of the guide: node, children (
listwith offset, limit and sort),childrenCount, fields, one field, the same by object; writes (create, update, delete) at v2 only. - Permissions (3 minutes). Every read and write checks
content/read,content/create,content/editorcontent/removeof the user the request runs as, whatever it was authenticated with. Answers: 200, 201, 400, 401, 403, 404. - Settings (2 minutes).
rest.ini:[System] ApiPrefix,[ApiProvider] ProviderClass[<prefix>],[Authentication] RequireAuthentication,AuthenticationStyle,RequireHTTPS.
Common questions
Why v1 and v2? Existing clients call v1 and get the same answers as before; writes were added at v2.
Is there a known problem? listAtom answers 500 (section 8 of the guide). Tell learners before they try it.
Does the REST interface use the view cache? It has its own answer cache in the framework; content permissions are checked for every request.
Pitfalls
ezprestapinot active. Without it the content routes answer as unknown. CheckActiveExtensions.- Changing
rest.iniwithout clearing the INI cache. Clear it, and reload PHP workers. RequireAuthentication=disabledon a live site. Requests then run asDefaultUserIDor anonymous; only for public read-only data.
Hands-on exercise
On the development installation.
- Check that
ezprestapiis active:php bin/php/console exp:ini get site.ini/ExtensionSettings/ActiveExtensions | grep ezprestapi. - Read the providers:
php bin/php/console exp:ini where rest.ini/ApiProvider/ProviderClass. - Read the authentication settings:
php bin/php/console exp:ini list rest.ini/Authentication. - Read the route table in the provider:
grep -n "new ezpMvc" extension/ezprestapi/classes/rest_provider.php. - For each route, write its path and whether it answers at v1, v2 or both.
- Call the API without credentials and read the status:
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8087/api/ezp/v1/content/node/2(use your address). - Find the kernel's REST framework folder and list its classes:
ls kernel/private/rest/classes/.
Expected result
- Step 1 prints
ActiveExtensions[]=ezprestapi(or the extension is listed in the value). - Step 2:
ProviderClass[ezp]=ezp7xRestApiProviderandProviderClass[ezpl]. - Step 3:
RequireAuthentication=enabledand the authentication style. - Step 6:
401, because authentication is required. - The trainer checks the route table of step 5 with the guide's table.
Quiz
- Which extension serves the content routes?
- At which versions do writes answer? A. v1 only B. v2 only C. v1 and v2 D. none
- What are the parts of
/api/ezp/v2/content/node/2? - Which policies does the REST interface check?
- What does a request without credentials get when authentication is required?
Answers
ezprestapi, with the providerezp7xRestApiProvider.- B. v2 only.
ApiPrefix/api, prefixezp, versionv2, path/content/node/2.- The user's content policies:
content/read,content/create,content/edit,content/remove. 401.
Further reading
Related pages
- Module 11: The REST API
- Developers: course overview
- Trainers: start here
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.