New Oro Web API
In our previous 1.9 release of Oro Platform, we have mentioned that we’ve started development on the new API. The new, automated Oro API Platform will be available on all Oro Products with the 1.10 release scheduled for end of July 2016. In this blog post we’d like to give the community developers a preview of its capabilities.
Oro’s REST APIs required developers to be implement APIs manually for each and every entity. This is inefficient and time consuming process and led to inconsistencies in API implementations and omissions of API methods for certain fields and entities. In addition, the old API had an adverse impact on the overall performance of our products.
To fix this, we decided to develop a completely new automated Oro Platform API that is based on entity metadata. This means that after you create an entity, all of its fields and relations become immediately available via API—so you can get their contents, create new records, and update and delete existing records immediately.
Let’s take a quick look at its capabilities.
What the new Web API can do?
The new API is based on JSON API specifications. It supports all standard HTTP methods for a RESTful service:
- GET
- POST
- PATCH
- DELETE
Note that JSON specs discourage the use of PUT method, so we use PATCH for updating the records.
Both GET and DELETE methods support massive operations with options for filtering and sorting the set of records. GET also supports field configuration, so you can limit the request with the specific set of fields.
API methods for sub-relations will be supported too. This means that you will be able to manipulate the exact record(s) from the collection of related entities—e.g. only the specific contact of an account.
Documentation for all API methods is (mostly) automatically generated. It can be accessed via the sandbox at http://YourOroPlatformAppURL/api/doc/rest_json_api.
Limitations and known issues
Currently, only GET and DELETE methods are available in the master branch. All capabilities listed above will be available in the stable 1.10 release.
The new API will be shipped without methods for manipulating record activities and contexts. We have plans to add them in the future releases though. (And we will happily welcome any community contributions!)
The filters only work for indexed entity fields out of the box. They can be configured to work with non-indexed fields too, but doing this might cause performance deterioration.
How do I enable the new Web API?
The new API is disabled by default for backwards compatibility reasons. You have to enable it explicitly for every new entity.
To do so, create api.yml file in Resources/config/oro/ and write the following configuration there:
oro_api:
entities:
AcmeBundleProductBundleProduct: ~
Then run php app/console oro:api:config:dump-reference command to get the basic configuration. AndB boom, you’re done.
Note that you may further custom-tailor the API configuration to your own needs. Most of the customizations may be accomplished by editing the api.yml config but in some extreme cases you might have to write your own PHP processor. Please read our documentation to learn more on the subject.
What happens to the old REST API?
The old API will be deprecated, but will still be available for at least the next two release cycles to give you the time to transition to the new API. We recommend doing it as soon as possible, as none of the new features will support the old API.
What are the benefits of using the new Web API?
- MUCH quicker API development: as simple as running a console command.
- Easier customization: most changes can be done in the config file.
- Consistency in methods: development and support will be much easier.
- Better performance: all requests will get quicker responses.
The new, automated Oro API platform addresses the important issues and limitations we have with our current APIs. Now our community of developers and partners can be more efficient with their development process and have an API platform with much improved performance
We are always eager to get your feedback, so please either comment on this blog or send us questions or comments via our forum.
Thank you!
The Oro Team
