Appearance
Upgrading to 10.0
10.0.0 is a major release. Read this page before you update: it lists what you have to check in your settings and in the API clients that call the webservice. All changes are in the changelog.
Make a backup of the files and the database first, and test the update on a copy of your site when you can.
Requirements
10.0.0 requires ExpressionEngine 7.3+ and PHP 8.0+. For ExpressionEngine 6 use the legacy package in the download (legacy/ee_webservice-v9.2.0.zip).
The add-on uses the ExpressionEngine 7 add-on installer and migrations. The automatic migration from the old Webservice module (before the reinos_ prefix) is removed: update to the legacy package first, then to 10.0.0.
Check your settings
API access per member
A webservice member only has access to the APIs that are selected in its member settings. Check the selected API(s) of your members before updating. See Creating members.
Credentials
Secrets, shortkeys and the super admin shortkey are shown once after generating them. Existing credentials keep working, but they can no longer be viewed in the CP.
- Shortkeys and the super admin shortkey are generated instead of typed in. See Shortkeys
- The secret and a new shortkey are shown once after generating them, copy them right away. See Key / Secret
- A shortkey is unique now. When more members had the same shortkey, only the oldest stays: API clients with that shortkey log in as that member. The update logs the removed shortkeys on the Logging page, generate a new shortkey for these members. See Logging
- A shortkey is case sensitive now: an API client must send it exactly as it was stored, otherwise it gets a
401
Member API and Comment API
The settings Member API and Comment API are off by default: when off, their endpoints do not exist. Turn them on when your API clients use these APIs. See CP Overview.
Free APIs
The Free Api(s) setting is replaced by the public endpoints in the endpoints overview. Existing free APIs are migrated. A free method of the Member API or Comment API is public again as soon as you turn that API on, so check these endpoints after turning it on. See Endpoints.
IP blacklist
The IP blacklist accepts a pipe, comma or new line as separator. See CP Overview.
Check your API clients
Member API
The Member API is part of the module, the separate Member API and Member Tools API packages are no longer needed. It checks the ExpressionEngine permissions, protects Super Admins, follows the registration rules of ExpressionEngine and returns validation errors per field with a 422. The data and the responses changed, see API Member.
Comment API
The Comment API is part of the module and follows the rules of the comment form of ExpressionEngine: permissions, moderation, the spam service and the notifications. A comment is always posted as the member of the request, and reads only return open comments without the email and IP address unless the member can moderate comments. Reads only return comments of the assigned channels of the member, on a public endpoint also of open entries in every channel. See API Comment.
Category API
The Category API is part of the module and read only: the categories (flat or as a tree, with the custom fields and the image url) and the category groups (with their fields and channels). The separate package is no longer needed. See API Category.
Discontinued packages
These separate packages are discontinued and do not work with this version:
- The Channel, Category Group, Member Group, Config, Template, Template Group and Template Router APIs. Managing these stays in the CP. The category groups are read with the Category API.
- The Parent Relationship and Structure extensions: use
include=parentsandinclude=structureonread_entry. See API Entry - The View Count API: use
POST /entry/view_count. See API Entry
HTTP status of the Entry API
The errors of the Entry API have an HTTP status (400, 403, 404 or 422) instead of 200, also No Entry found when a search finds nothing. The response still has "success": false and the message. Check API clients that treat every status other than 200 as a failure of the request, or that only read the body on a 200. See API Entry.
Empty values in read_entry
read_entry returns every key of an entry, also when the value is empty (0, "" or false). Before, these were left out. Check API clients that test whether a key exists.
Searching with not
not test in a search of read_entry now means does not contain, as documented. Before, it was an exact not-equal, so it finds fewer entries now. Use not =test for the exact not-equal. See API Entry.
The author of an entry
read_entry with include=author returns the email of the author to the author itself or a member with the permission Access members, the ip_address of an entry goes to members with that permission. See API Entry.
Sessions
An API call with a shortkey, key/secret or username and password no longer leaves a session behind or sends a session cookie. The session of the Auth API stays, to use it with X-Session-Id.
A session follows the rules of the sessions of ExpressionEngine: it expires after two hours without a call (one hour for a member with access to the control panel), and it only works with the same User-Agent as the login. Check API clients that keep a session for a long time, or that log in from another client than the one that uses the session.
HTTP status of the Auth API
A failed login on the Auth API gives a 401 with the message cannot auth with given data instead of a 200. Check API clients that only read success.
HTTP status of an inactive member, an API without access and a blocked IP
A member that is not active gets a 403 instead of a 404, a member without access to the API a 403 instead of a 501 and an IP on the blacklist a 403 instead of a 401. The message stays the same. Check API clients that act on these statuses.
Credentials on public endpoints
Credentials on a public endpoint get the same checks as on any other endpoint. Wrong credentials or an expired session give a 401, also a member that is not added to the module gets a 401. An inactive member or a member without access to the API gets an error too. Check API clients that send credentials or an X-Session-Id to public endpoints.
Entries on public endpoints
A guest only finds open entries on a public endpoint, also with status in the data. A member finds the open entries and every status of its assigned channels. Sites with custom statuses for public content: those entries need credentials.
After the update
- The control panel pages use the ExpressionEngine 7 control panel routes. The endpoints overview is the landing page of the add-on (
addons/settings/reinos_webservice), the old/endpointsand/api_overviewURLs no longer exist. - Delete the API logs from before the update on the Api Logs page. See Logging
- An update keeps the current Debug setting. Log requests logs the calls for the statistics. See CP Overview
For developers
When you have your own API or custom code that uses the webservice:
- The
entry_submission_endhook is removed, useafter_channel_entry_saveandafter_channel_entry_delete. - The
act_routeaction, thecp_js_endhook and the undocumented{reinos_webservice_action_url}global are removed. - The cache key contains the site, so the cache can be cleared per site and per endpoint. See Cache
- An API can register more HTTP methods for one route (e.g.
PUT|PATCH), and the parameters of a route are part of thedata. See Your own API
