One of many goals for Magento 2 has been to improve the web-based APIs (REST and SOAP). Well, another cool step forward here has just been made – you can now request a JSON Schema listing all the REST URLs supported by your site. (WSDL files for SOAP APIs are already supported.)

Fetching the Schema

My suggestion is to start by fetching the REST API schema for your site. On my local developer box, I have a few things running in my web server, so the URL I gave my web browser was

  http://127.0.0.1/index.php/rest/default/schema

In production you would not include the “index.php” portion of the URL, and you would put your domain name in instead of “127.0.0.1” (localhost). The only other part of the URL that may change for your site is “default”. This is the store view code. To see what store view codes are available, go to the Admin interface, “Stores”, “All Stores”. This will return a list of Web Site/Store/Store View triples for your site. Click on the third column (“Default Store View” for a default installation). The “code” field there will be “default”. (Beware there is a “code” field also for the first column “Web Site”, which is set to “base” – that is not the right value and tripped me up for a little.)

You should see output coming back that starts with something like the following:

  "swagger": "2.0",
  "info":
  {
    "version": "1.0",
    "title": "Magento Community"
  },
  "host": "127.0.0.1",
  "basePath": "/index.php/rest/default",
  ...

Note that the default JSON returned is not pretty printed – it will appear as one very long line if you fetch it using a tool like curl. My web browser pretty printed the above output to make it easier to read.

Why is this useful?

Have you ever wondered if the API documentation you are reading is completely up to date with the latest software patch? Or maybe you are using a previous version of the software and do not have the old documentation handy. Having the supported REST URLs generated directly from the site means you get back a definition that you can trust as being 100% up to date with the code base.

This is particularly useful as sites are frequently customized by the addition of extensions. In a previous post I demonstrated how to easily add your own REST APIs. If you load that module, the REST schema returned will include the extra REST URLs exposed by the extra module.

So using the built in ability to fetch the schema means you can always be sure you are getting the exact URLs supported by the site, taking into account which modules are active.

How to Read the Schema

For those who do not enjoy reading a 31 thousand line pretty-printed JSON document, there are tools around to generate are more human friendly version of the schema. Swagger is a popular tool for this (the Swagger project defined the JSON document format that we are returning to describe the schema). For a hint of what it would look like you can see their online demo petstore.swagger.io .

If you want to view the documentation for your own site, the online petstore site can accept the URL of your local site (replace the URL “http://petstore.swagger.io/v2/swagger.json” in the text box near the top of the page). This works even if the URL uses “localhost” and not exposed publicly to the Internet. However, you need to add an extra header to get around some CORS protection issues. The quickest solution is to add the following line to the top of your Magento root .htaccess file:

  Header set Access-Control-Allow-Origin "*"

This sets an extra HTTP header to allow it to work, but do not do this in production unless you fully understand all the security ramifications. I am suggesting it here only as a quick and dirty solution so you can experiment easily.

If you have loaded my sample calculator web service module, the first entry should be “alanKentCalculatorWebServiceCalculatorV1”. If you click to expand you should see

You can click further to expand the first “add” service and type in sample parameters like “2” and “3” and see “5” come back as a response. The excitement never ends with Magento 2!

Official Documentation

The Magento documentation team has been keeping up with latest developments too. There is an online site (still under development) making similar documentation available for the base Magento CE installation. See http://devdocs.magento.com/guides/v2.0/rest/rest-details.html for a link to a generated site.

Note that the Magento documentation site is only for the default installation and will not include any local customizations for your site.

So Who Cares?

I personally think this sort of stuff is pretty cool.

• Integration: Improving our REST (and SOAP) support continues to lift Magento’s game in the area pf being an open and extensible platform. This is great for integrators – you can be sure you are getting exactly the right API available for the site you are dealing with, and you know the exact breadth of the available API.
• Learning: The REST schema includes definitions of the data structures passed into and returned from REST services. My last post used the REST schema to generate UML like diagrams automatically from the JSON returned with 160 lines of PHP code. I find these sorts of diagrams great for understanding just the data structures involved in a Magento site.
• Headless Magento: I think there are lots of interesting possibilities in a headless-Magento, say for supporting an Angular based UI. Magento provides REST based services for access to products, the shopping cart, and checking out – leveraging all the Magento functionality and extensions around shipping, tax, drop ship, and so forth. This also opens up options to add Magento functionality to your existing site without having to revamp the whole UI – perhaps a WordPress or Django extension would be possible.

Personally I think the expansion of APIs is going to make some pretty interesting use cases much easier to tackle with Magento 2.

Conclusions

Exposing the REST schema via JSON is another step in making Magento 2 easier to access. While the ability to fetch REST schemas is now working, the team is always looking for feedback on how to make things better. For example, being automatically generated from the source code, the grouping of URLs may not be as intuitive or digestible as desired yet. Do you have an idea how to make it better? We would love to hear it, and any other feedback on the REST APIs in Magento 2.

Disclaimer: This is my own opinions, errors above are my own.