Introduction
Recently, I was working with a REST API where I needed to register a user account. I decided to reuse the core user registration REST API, however, the only problem was that the error messages were not user-friendly.
At that time, I felt the need to alter the exception messages thrown by the core REST API. I got the opportunity to explore the REST API workflow and discovered the 'Event Subscriber' approach that could be used.
Example
Let’s take a very generic scenario: a user tries to create an account with an email ID that already exists. When the REST API endpoint is hit at the backend, a more user-friendly exception message is thrown from the core user registration API using the 'Event Subscriber' approach through customization.
Default core user registers Rest API thrown error message:
"message": "Unprocessable Entity: validation failed.\nmail: email address nia@gmail.com is already taken.\n"s
Custom thrown error message for core user register REST API: By using event subscriber approach: see attached screencast for demo:
"message": "The email address nia@gmail.com is already taken."
Steps to alter error messages thrown from core REST API
Steps to alter the error message thrown from core REST API by using the “event subscriber” approach:
1. Create a new service: “custom_rest_validation.custom_rest_validation_subscriber” in which tags key pass event_subscriber & class key pass name of the class that needs to call when this specified event subscriber calls.
Note: Services are defined in a file called 'custom_rest_validation
.services.yml', assuming that your module is named 'custom_rest_validation. This file should be located in the root directory of your module project.
2. Create an event subscriber class that is attached to the newly created service in the above-mentioned step.
Here, getPriority() handles the exceptions we want for JSON calls before core subscribers (with priority -70/-75). Therefore, it is given a higher priority value (-69) than the core subscriber.
Here, onException() handles errors for this subscriber and is used to throw custom exception messages. A condition is added so that the custom exception is thrown only for the user registration API and for the email field.
Here call the custom parseErrorMsesage($msg) conditionally, which returns a human-readable user-friendly error message “The email address example@gmail.com is already taken.” if the user enters an existing email while creating a new user account.
Note: The event subscriber class CustomExceptionSubscriber.php will be placed in the following folder structure: root_folder_module/src/EventSubscriber/.
We can alter the exception message of the core REST API by extending an "event subscribe" approach.
Conclusion
This approach allows you to utilize the core REST API implementation and integrate desired functionality to provide more human-readable, user-friendly exception messages to end users, thereby enhancing the user experience. The following actions are implemented using the REST API:
- Get data from the endpoint (GET request)
- Create data at the endpoint (POST request)
- Update data at the endpoint (PATCH request)
- Delete data from the endpoint (DELETE request)
Reference links
For more details about the REST API, you can follow the GitHub demo link. For example, in this demo, I have altered the error message of the core user registration API. If a user enters an existing email ID, a custom exception message will be thrown instead of the default error message from the core REST API for user registration.
Rest API: documentation