A common problem that developers run into when developing against Magento 2 APIs is that the documentation is not very good. A lot can be done with an OpenApi (formerly Swagger) spec and the Swagger UI tool is great for testing, but when forces in the world are shifting more and more towards mobile development, the strength and use of APIs becomes much more important. Along with that, documentation is key, but is often times done as an after thought or auto generated from code. Regardless of that, this blog post is about one particular problem that I have with a particular API call.
Magento has an Admin REST API which accepts the standard searchCriteria parameters with the route:
GET /V1/products/attribute-sets/groups/list
Based on the definition in the spec and the limited documentation, one would expect that this would allow for searching across all attribute groups, or to simply get a list of all attribute groups that are defined within the system. Using the search parameters as one would expect will result in an error with the response message:
{
"message":"%fieldName is a required field.",
"parameters":{
"fieldName":"attribute_set_id"
},
"trace":"STACKTRACE INFORMATION"
}
This makes no sense because attribute_set_id is not one of the parameters and is a source of confusion across the interwebs.
As it ends up, this call actually only allows for listing all attributes that belong to a particular attribute set. The “search parameters” are not really search parameters as one expects and only work if set as such:
searchCriteria[filterGroups][0][filters][0][field]=attribute_set_id
searchCriteria[filterGroups][0][filters][0][value]={{SOME_ATTRIBUTE_SET_ID}}
Any other parameters seem to be ignored and are meaningless.
This combination of path and parameters is very confusing and does not follow a standard REST collection/resource design pattern. There is another route that is a PUT /V1/products/attribute-sets/{attributeSetId}/groups which has a more logical path that could be used for this GET call, but this is unfortunately not how the world is, but hey, the future is coming. 🙂
One simple suggestion for the Magento team: why not have wiki documentation for the APIs as well as just the spec and some simplistic examples?
