How to use the Modx Revolution API

Question

I have a client who is looking at having some other company develop an iPad application that will pull resources out of their existing modx instance. [no - I don't know why it needs to be an app.... ]

They are looking to use the Modx API, which from what I can tell so far needs to have a connector or something written as it does not "just work" correct?

So basically I need to write a connector that will handle the authentication [API key type idea] and pass all the data back and forth? Looking here: http://rtfm.modx.com/display/revolution20/Loading+MODx+Externally I see two methods of connecting/using modx - what is the advantage of "loading modx externally" over "Loading modx in api mode"

I found the API documentation easily enough but pretty much ZERO on actually using it.

So:

1. are there API usage docs anywhere?
2. what is the advantages/pro/cons of the load external vs. load as api methods
3. are all my assumptions above correct, or did I miss something really basic?

Answer 1

Documentation that you have found enough to use API modx. Once you connect mode API ( http://rtfm.modx.com/display/revolution20/Loading+MODx+Externally - The third example I like best ) You can use modx processors to do whatever is necessary, as example authenticate the user:

if(isset($_POST) && count($_POST)){
    $c = array(
        'username' => $_POST['username'],
        'password' => $_POST['password']
    );
    $response = $modx->runProcessor('security/login',$c);
    if($response->response['success'] == 1){
        $user['id'] = $modx->user->get('id');
                $profile = $modx->user->getOne('Profile');
        $user['fullname'] = $profile->get('fullname');
        $user['email'] = $profile->get('email');
        echo json_encode($user);
    }else{
        echo json_encode($response->response); 
    }
}

simple getting resources:

if ($res = $modx->getObject('modResource', 1)) {
    print_r($res->toArray());
}

or advanced getting:

$response = $modx->runProcessor('resource/get', array('id' => 1));
if (!$response->isError()) {
    print_r($response->response['object']);
}
else {
    $modx->log(modX::LOG_LEVEL_ERROR, $response->getMessage());
}

Answer 2

ModX documentation hasn't been its forte over the years, but here are few links.

First, understand how ModX works and was architected so you can develop with/for it.

ModX's API reference is at http://api.modx.com. There you will find all the methods available, its properties and parameters. It's not a guide but a reference so don't expect too much literature.

Since version 2.3 you can build your own API on top of ModX. Very useful for customizing RESTful endpoints but unless you have some experience working/building API's this might be challenging.

Finally, if you're looking for a more in-depth documentation check out the books.

For example this is how you'd make the ModX object available from outside:

<?php
require_once '/absolute/path/to/modx/config.core.php';
require_once MODX_CORE_PATH.'model/modx/modx.class.php';
$modx = new modX();
$modx->initialize('web');
$modx->getService('error', 'error.modError');