Exciting things

OctoberCMS – setup API development the right way

I have a need to setup API development with OctoberCMS. Basically, there are many options for me to make it works:

  • Option 1: I can create an API just by creating new page in the CMS and write the code to query data and return JSON output directly => quick and dirty way
  • Option 2: Create new routes under the routes.php config file in the cms (or backend) module. Then writing Controller in cms (or backend) module.
  • Option 3: trying to inject the https://github.com/dingo/api into OctoberCMS. However, same questions that we need to solve: where I should put route configuration and my controller classes?

After diving deeply to the way that OctoberCMS loading configuration and its modules, finally I have figured out the approach:

Step 1 – Inject Dingo API library to OctoberCMS

Dingo API is a great library that help us to wrap many complicated things when developing APIs, from security, versioning …. You can following steps at https://github.com/dingo/api/wiki/Installation for the configuration.

Please be noticed that: if you install OctoberCMS by command line, you cannot find the composer.json file inside your source code. In that case you need to download the composer.json from OctoberCMS Github repository and then run the command ‘composer update’ again in your OctoberCMS folder.

Step 2 – Setup a new module to write your API code

I decide to create a new module called Api. We can do it simply by creating a new folder at the same level with cms (or backend module) folder. Then, inside this folder, you will create the ServiceProvider class similar as below:


Check the code here.

Next step, we need to load the module. We do it by go to the file config/cms.php. At there, you will see this line:

'loadModules' => ['System', 'Backend', 'Cms'],

You can add our new module to this array. Be careful with the name. You need to use the same name that you register for your module in the above ServiceProvider class.

Now, you can add routes.php configuration file into the new module folder. Also, you can create controllers folder to contain your Controller classes. Further than that, you can do whatever you want in your module folder structure.

Finally, the module will have the structure like this:


In my case, as I don’t want to have the Cms module (as my system just need API and the backend), I simply remove the Cms module in the loading module array. It helps to reduce unnecessary things in the loading process.

Why I would recommend this way?

Basically, this approach is not written anywhere in the OctoberCMS documentation. However, I strongly believe that in the case you need a new module which affect strongly to the way that OctoberCMS loading its classes, you need to follow the Provider pattern and make your own module. It helps to:

  • Reduce the bootstrap process and improve the processing speed or you can interfere to the bootstrap process if you want.
  • Make the code structure cleaner and well organized.

This approach is very common when we work with pure Laravel framework/ Symfony.

Hope this helps.


5 thoughts on “OctoberCMS – setup API development the right way

  1. Raja

    Interesting approach. I am wondering if this module gets deleted during core updates ?
    What are the disadvantages of using this method instead of writing plugins.

    1. khoatran Post author

      I have a personal project using this approach, but cannot share the full source code here. However, I shared the whole idea of the approach for developing the API module on OctoberCMS in this post.

Leave a Reply to Raja Cancel reply

Your email address will not be published. Required fields are marked *