Web-services examples in Salesforce

APIUtils.java

/**
* This class is a utility class for WebServices and other API classes
*/
global with sharing class APIUtils {
    global final static Integer STATUS_OK = 200;
    global final static Integer STATUS_CREATED = 201;
    global final static Integer STATUS_ACCEPTED = 202;
    global final static Integer STATUS_BAD = 400;
    global final static Integer STATUS_FORBIDDEN = 403;
    global final static Integer STATUS_NOTFOUND = 404;
    global final static Integer STATUS_NOTALLOWED = 405;
    global final static Integer STATUS_ISE = 500;

    public virtual class UnknownException extends Exception {}

    /**
    * This class is an abstraction of the MyObject__c object
    */
    global class APIMyObject {
        WebService Integer returnCode;
        WebService String message;

        WebService String name;
        WebService Boolean isAwesome;
        WebService String myField;

        /**
        * A blank constructor
        */
        public APIMyObject() {}

        /**
        * A constructor based on MyObject__c
        * @param o My Object
        * @param awesomeness Is the object awesome
        */
        public APIMyObject(MyObject__c o, Boolean awesomeness) {
            this.name = o.Name;
            this.myField = o.MyField__c;
            this.isAwesome = awesomeness;
        }

        /**
        * A constructor based on MyObject__c
        * @param o My Object
        */
        public APIMyObject(MyObject__c o) {
            this(o, true);
        }
    }

    /**
    * This class is list of APIMyObjects
    */
    global class APIMyObjects {
        WebService Integer returnCode;
        WebService String message;

        WebService List<APIMyObject> myObjects;

        /**
        * A blank constructor
        */
        public APIMyObjects() {}

        /**
        * A constructor based on a list of MyObject__c
        */
        public APIMyObjects(List<MyObject__c> objList) {
            this.myObjects = new List<APIMyObject>();
            for (MyObject__c o: objList) {
                this.myObjects.add(new APIMyObject(o));
            }
        }
    }
}

MyObjectAPI.java

/**
* This class is a webservice that returns information from the MyObject__c level
*/
global with sharing class MyObjectAPI {
    /**
    * This class is passed in from the client to specify the calling context
    */
    global class AccountContext {
        WebService String accountNumber;

        /**
        * A blank constructor
        */
        public AccountContext() {}

        /**
        * A constructor based on an account
        * @param a An account
        */
        public AccountContext(Account a) {
            this.accountNumber = a.AccountNumber;
        }
    }

    /**
    * Gets all related MyObjects for a given account
    * @param context The account context
    * @return The related MyObjects
    */
    WebService static APIUtils.APIMyObjects getMyObjects(AccountContext context) {
        APIUtils.APIMyObjects result = new APIUtils.APIMyObjects();

        if (context == null || context.accountNumber == null || context.accountNumber.trim() == '') {
            result.returnCode = APIUtils.STATUS_BAD;
            result.message = 'Invalid account number';
            return result;
        }

        try {
            Account acct = MyObjectUtils.getAccount(context.accountNumber);
            List<MyObject__c> myObjs = MyObjectUtils.getObjectsForAccount(acct);

            result = new APIUtils.APIMyObjects(myObjs);
            result.returnCode = APIUtils.STATUS_OK;
        } catch (APIUtils.UnknownException e) {
            result.returnCode = APIUtils.STATUS_NOTFOUND;
            result.message = e.getMessage();
        } catch (Exception e) {
            result.returnCode = APIUtils.STATUS_ISE;
            result.message = e.getMessage();
        }

        return result;
    }
}

MyObjectUtils.java

/**
* This class handles MyObject logic
*/
public with sharing class MyObjectUtils {
    public class UnknownAccountException extends APIUtils.UnknownException {}
    public class UnknownObjectException extends APIUtils.UnknownException {}

    /**
    * Gets an account from a given account number
    * @param accountNumber The account number
    * @return The matching account
    * @throws UnknownAccountException if the account number is not found
    */
    public static Account getAccount(String accountNumber) {
        if (accountNumber == null || accountNumber.trim() == '') {
            throw new UnknownAccountException('accountNumber null or blank');
        }

        Account acct = null;

        try {
            for (Account a: [
                select AccountNumber,
                    Name
                from Account
                where AccountNumber = :accountNumber
                limit 1
            ]) {
                //Check to make sure SOQL injection wasn't used
                if (a.AccountNumber == accountNumber) {
                    acct = a;
                }
            }
        } catch (Exception e) {
            acct = null;
        }

        if (acct == null) {
            throw new UnknownAccountException('Unable to find account by accountNumber');
        }

        return acct;
    }

    /**
    * Gets all the related MyObject__c for a given account
    * @param a An account
    * @return A list of MyObjects
    */
    public static List<MyObject__c> getObjectsForAccount(Account a) {
        if (a == null || a.Id == null) {
            throw new UnknownAccountException('Account is not valid');
        }

        List<MyObject__c> myObjs = null;

        try {
            myObjs = [
                select Name,
                    MyField__c
                from MyObject__c
                where Account__c = :a.Id
            ];
        } catch (Exception e) {
            myObjs = null;
        }

        if (myObjs == null) {
            throw new UnknownObjectException('Something went wrong');
        }

        return myObjs;
    }
}