To get an understanding of the history of REST and transformations REST to RESTful you may want to read this article RESTful Vs REST API Or Where Did REST Come From?
When you have a task to build a REST API or a web application with exposed API you need to answer a lot of questions like:
- Public or private API
- The business value of the API
- Target audience or who will consume it
- Regions of the consumers
- Security and permissions
- Future updates and versioning
- Schema and data format
- Use limits, plans, and policies
- Monetization aspects
- Tracking and management
If to talk about schema, formats, and design of the Web service I would say, a specific protocol is not so important as the transportation semantics of your API. The most common anti-pattern is using an anemic or data-centric API in services with the complex business subject area since REST encourages developers to use the flat CRUD API approach instead of logical endpoints semantics. You can read more regarding AnemicDomainModel in the Martin Fowler article from 25 November 2003.
Using a data-centric API approach you are getting usually an HTTP gateway to your database tables or collections. Such a flat API due to data centricity will expose relations of the database entities and in complex systems may require you to have deep rest routes like POST "api/company/{companyId}/department/{departmentId}/office/{officeNumber}/employees" instead of having POST "api/set-employees-workplaces".
With CRUD structure once you need to have changes in multiple tables, you will have to do 2 different queries and the consistency of your changes will be at the risk due to network or any other issue. In this case, having simple CRUD APIs enforce you to build a separate service to make orchestrations for scenarios where you need a kind of atomicity or transaction handling and perform business logic and validations. Also, there might be a case of changing entity to a different state which is not allowed by business logic according to related data in different stores, for example, the employee can not be removed from the system in case this person is a class teacher and has assigned lessons.
In business systems, there might be lots of cases when it will be required to add validations or business rules. When the development of the system never ends data-centric API will be rewritten multiple times once new rules appearing. In this case clients of such API also will be affected.
So in case, the system has generic almighty actions with the names like "updateEntity()" or "editEntity()" this means that there are no validation and business rules on the other hand actions may have names of business operations, this will tell that endpoint will only make changes of the business intent, will perform validation and ignore redundant fields in the request.
This is easy to build a flat CRUD API since there are lots of libraries in different languages which can do this almost out of the box, but before developing a new Web API think twice about whether it should be a datacentric API with an anemic domain model or a rich and smart API which describe the intent of the business processes in almost every endpoint.
Please feel free to add more cases to the comments where the datacentric RESTful API will not be the best choice, I will update the article accordingly.
Next, you may want to read the article RESTful API patterns or RESTful in practice which is coming soon.