Building an add-on that accepts data from a custom front-end URL

Question

My goal is to have a REST endpoint that I can push AJAX requests to, have those requests be parsed, potentially push some data into the DB via a channel, and then return a JSON status message. I don't want to have to put PHP into a template to accomplish this, and am happy to write an add-on of some sort.

Please don't suggest add-ons. I want to know how I would go about writing my own add-on to accomplish this.

My question:

From a high level, how would I start writing this add-on? Specifically, how would I route a custom URL to my add-on code? What type of add-on should I be building for this (i.e. Module, Extension, something else)?

This is something I've done a number of times with other web frameworks (including CodeIgniter), but for some reason I'm finding it very difficult to get information on how this would be done in EE.

EDIT: I've tried to make this question more clear. I'm specifically looking for advice about add-on creation. Based on my re-reading of all the EllisLab add-on docs and a lot of time searching the web, I'm starting to feel like this isn't something EE can do without an incredible amount of hacking. I'm really hoping that's not the case.

Answer 1

It's certainly possible without hacking. Just that the EE documentation isn't particularly helpful on how to handle this sort of thing.

Basically, you want to write a Module. Then you need to register an "action" in your module's install script:

$data = array(
    'class'     => 'Module_name' ,
    'method'    => 'method_to_call'
);

$this->EE->db->insert('actions', $data);

Bingo. This will give you an endpoint which you can use to create your API (this is how all EE modules work when handling form submissions from the front end). You action will get an ID like 123, and will be accessible at http://www.example.com/index.php?ACT=123. This will then call the method you specified in the install script (this method must be defined in your class in mod.addonname.php).

Now you can check input data, access the database, return JSON... whatever you like. For an example of this in action, check out FreeMember.

Note: This doesn't involve any routing, but it builds a perfectly valid web service endpoint. If you want custom routing, the only way to go is to create an extension using the sessions_end hook, and add your own router code which checks for specific URLs and handles the response. It's WAY easier to just work with EE's built in ACT handling.

Answer 2

I've thought more about this. Based on the pre-condition you're building a custom addon to handle this, the only way I can see it working would be to either :

1. Create a dummy top level template group (ie. called 'api' with a sole tag to your custom addon : {exp:restful_api:handle}. From within there you could do any and all the parsing/restful interactions that you'd need. That's a fair amount of work and you'd need to be careful EE's not fighting you with parse orders or other built in core mechanisms.

2. An option would be to try and see if the core_template_route hook fires early enough to be of use to you. If that fires early enough, use that to hook against the calls, do some basic filtering, and if the route appears to be one you want to have you're custom handling (ie. matches foo.bar/api/...) kick into your custom handling. You'd need to kill out any actual following EE handling, but if you're going custom regardless that might work.

(If the core_template_route hook fires too late, you might need to find an earlier hook. But in principle it's possible, if a bit unusual. )

Answer 3

Switchee is a plugin that will let use switch/case logic in your EE templates and allow you to use your template more like a controller, responding with different chunks of code based on the variable/s you test against. I will commonly use it and test against EE's segment variables so I can combine a channel listing and single entry into the one template, creating a more succinct URL structure than the standard EE template-group/template/variable URL. You could also use it to setup a simple API.

There are also a few routing add-ons for EE -- Freeway and Router -- that may be what you are after. I haven't used either but there is a comparison on StackExchange.

Answer 4

One method (al-be-it a bold one), would be to side-step the EE routing and templating entirely.

Create a new folder at root level within the site, ie. called 'api'. Within that drop a custom CodeIgniter (or anything really) application that would act as your API controller.

Chris Imrie built exactly this for an EECI talk. Have a look at - EE Data API.

From the best of my memory, that's a read-only setup, but it wouldn't take a huge leap to extend it to have write functionality too.

The advantage of having it as a standalone setup, is that you'll keep full control over every part of the api that'd you'd need to implement. Which, depending on the complexity of what you're building might be a good thing. It can be fully restful, have extra authentication, etc.. anything you'd need, and it wouldn't interfere with your existing site.

Answer 5

I've used a combination of Switchee and Freebie for this kind of thing in the past. Switchee sets up cases for a segment variable and Freebie makes EE ignore certain words so it doesn't reroute the template or alter how a tag is displaying entries. For instance, using the same template to show a success message after submitting a contact form.

For example, this contact form would redirect to the same URL with the word /thanks added upon successful form submission:

{exp:switchee variable = "{freebie_2}" parse="inward"}
  {case value="thanks"}
    Thanks for submitting the contact form!
  {/case}
  {case default="yes"}
    *(contact form code goes here)*
  {/case}
{/exp:switchee}

Note: You have to use {freebie_2} instead of {segment_2} to include words in Freebie's segment list that EE would otherwise ignore.