SugarCRM Cookbook – Adding a REST endpoint

sugarraagaard —  March 10, 2014 — 3 Comments

So you’ve seen what the REST API can do and you want more. In this recipe we’ll be covering how to create your own REST endpoint.

Our sample endpoint is going to go beyond the filter API and give us a list of accounts ordered by the number of open cases.

1. Deciding on an endpoint location

This is just about the most important step in adding a new endpoint. The URL of an endpoint should be created using RESTful ideas and placed in the virtual directory tree in a way that will make it easy for developers too see the original intent of this API.

Since this endpoint is just going to be reading data let’s make it a “GET” request.

Because we are dealing primarily with account data we’ll throw it in “/Accounts“.

To finish it off we’ll name the endpoint “at_risk“.

So with it all together our endpoint is “GET /Accounts/at_risk“, now we could have our URL set to anything else but with a descriptive name and using the correct HTTP verb of GET it will help any other developers coming across calls to this endpoint to better understand what we are asking for.

2. Creating the endpoint class

The REST service looks in a lot of locations for endpoint classes:

  • clients/:platform/api/*
  • modules/:module/clients/:platform/api/*
  • custom/clients/:platform/api/*
  • custom/modules/:module/clients/:platform/api/*

Since we are adding a custom accounts endpoint we’ll create a new class “AtRiskApi” and put it in the file “custom/modules/Accounts/clients/base/api/AtRiskApi.php“. It is important to name the file so that it is the same as the class name except with .php at the end otherwise the REST service won’t find our class.

To get this class so it is listening for a specific URL we need to add a function ->registerApiRest(). We are setting the path to array(‘Accounts’, ‘at_risk’) and set the pathVars to array(”, ”) to represent “Accounts/at_risk” and not bring any part of the URL in to our array of arguments. If we wanted to match against a wildcard to look at the at risk profile for a single account record for example we could add a path of array(‘Accounts’, ‘?’, ‘at_risk’) and a pathVars of array(”, ‘id’, ”) which would let us listen for “Accounts/*/at_risk” and would take the second part of the path and populate the id element of our arguments with it.

Next we will actually add a function, setting the method in our register array to getAtRisk lets the REST API know to call that method in this class. We’ll keep this method simple for now and just have it return ‘burgers’ just so we can tell it is working right away. These methods just need to return data and the REST API will take care of all the json encoding for you.

Finally we add a little line in the shortHelp giving a quick description of what this endpoint is for. We’re leaving the longHelp out of this little demo but if you are building endpoints for real be sure to add some detailed documents there.

So, after everything is all said and done, here’s what our little class looks like:

3. Taking it for a test drive

Let’s do a GET request for /rest/v10/Accounts/at_risk

curl -X GET -H OAuth-Token:some-token http://localhost/burgers/rest/v10/Accounts/at_risk

And here is what we get back:

Hey, what gives? First things first let’s check to see if it registered correctly by looking for the endpoint definition in /help, navigate over to /rest/v10/help in your browser and look for it. Not there? didn’t think so.

We added the class and it didn’t load. Since the REST API looks for so many files in so many directories we have to add some heavy duty caching in order to speed up the url lookup on every single request. In order for changes in endpoint definitions to show up we need to login as an admin and run quick repair and rebuild.

After quick repair, let’s check /rest/v10/help again and you should see a line like this:

snapshot1

So let’s try that request again.

curl -X GET -H OAuth-Token:some-token http://localhost/burgers/rest/v10/Accounts/at_risk

Now we get back the correct response:

4. Fetching the data

While having a new URL that says “burgers” is pretty fancy I think we can accomplish more. While there are many ways to fetch and return this data I want to show you the preferred way to do it in Sugar 7.

First things first we need to start off by using SugarQuery. Let’s get a seed bean going by fetching a new bean from the bean factory. We pass that through to the SugarQuery ->from() method to let SugarQuery know we will be querying off of the Accounts module. We’ll limit our result set to just ID’s by adding ->select(‘id’) and then limit our rows to just the first five by adding ->limit(3). From here we can just have it return the results of the ->execute() call and see what that gets us.

Now our getAtRisk function looks like this:

and when we make that same GET request to Accounts/at_risk we get back:

Okay so now we have some simple SQL being run and are returning the result set. How about we add some more complex logic here so we actually fetch the results we want. To start things off let’s join in the cases by adding this “$caseAlias = $q->join(‘cases’)->joinName();“. It’s nice that we just need to use the link field to add a join and everything else is handled by SugarQuery. SugarQuery also understands that we have to go beyond it’s abilities every once in a while, so we need to add a ->fieldRaw() call to fetch the count and then an ->orderByRaw() to properly sort them. We have to use the Raw versions of the functions because neither of those columns are defined in the field_defs for the modules. The ->groupBy() call just needs to group by the account ID so that is simple. Finally the ->where()->notIn() is there so we only fetch related cases that aren’t resolved, no need to quote elements here because SugarQuery will handle that for us.

Added all together it looks like this:

Once again let’s hit Accounts/at_risk and see what we get:

Looking good! Now we are getting the data we need how about we make it look nice for the javascript client that needs it?

5. Formatting the data

To format the data first we have to figure out what to format. Most endpoints accept the argument fields to specify which fields they want returned from the api and we’ll keep up that tradition here with some simple parsing of the $args array.

Next up we want to convert the results of the query into beans so they can be properly formatted. Previously you would have to perform the PHP equivalent of banging two rocks together to make fire by manually fetching the rows and creating beans and populating them via ->populateFromRow(). Fortunately we are introducing a helper function in SugarBean named ->fetchFromQuery() to help automate and centralize this process, so we’ll just call that here. We need to pass ->fetchFromQuery() the option of returnRawRows because we need to populate the case_count field manually because it doesn’t exist in any of the field definitions.

With the beans returned from ->fetchFromQuery() we strip out the raw rows from the result set and then pass the remaining beans through to ->formatBeans() so that our returned results look the same as every single other API call. After we get the results back as an array from ->formatBeans() we loop through the results and jam the case_count in there.

So with all that, here’s what our final method looks like:

And when we finally call the Accounts/at_risk, here is what we get:

curl -X GET -H OAuth-Token:some-token http://localhost/burgers/rest/v10/Accounts/at_risk?fields=id,name,date_modified

6. All done!

That’s all, I hope this clears how to add your own endpoint to Sugar 7. Along with some helpful tips on how to use a combination of SugarQuery, ->fetchFromQuery() and ->formatBeans() to create easy and standardized code for returning data from the API. Add a comment if you have questions.

3 responses to SugarCRM Cookbook – Adding a REST endpoint

  1. 

    So I think “endpoint” stands for “entryPoint”? what if I want to use a legacy entryPoint?

  2. 

    and would you please post a gist or something to issue the GET using php?. How do I get the oauth token in php?

Trackbacks and Pingbacks:

  1. SugarCRM Cookbook – So you wanna override an endpoint « SugarCRM Developer Blog - March 21, 2014

    […] probably learn how to add a new API so you could use that instead and for that I will point you to Adding a rest endpoint.With that taken care of let’s get started on modifying an existing […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s