Salesforce REST API with managed Package

Question

We have implemented a rest service within a managed package. A few of our customers have already installed this package. Currently it takes 3 parameters. The purpose is to send updates made in one system to a Salesforce instance with the managed package installed. In building this service we followed the examples outlined here…..

https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_methods.htm

We want to add an optional parameter to our POST method call. Go from 3 parameters to 4 for example. We want this change to be backward compatible. What we see in trying to test this is a “Resource Not Found” error when sending 4 parameters rather than the old 3 parameters.

Is it possible to just update the rest service code without having all our customers install the package again? Or Does anyone who has installed the managed package have to go out and get a new package in order to read the new parameter? What is the best way to manage changes or updates like this?

Is there a better implementation or way to deal with this kind of scenario? Is it the responsibility of the invoker to determine the API/package version installed and pass in three or four parameters?

If you can share the best practice around upgrading REST API method implementation within salesforce it is really appreciated.

Example Old Way: ../apex/updateSomething sent with json in body {"Element1":"Value1","Element2":"Value2","Element3":"Value3"}

Example New Way: ../apex/updateSomething sent with json in body {"Element1":"Value1","Element2":"Value2","Element3":"Value3","Element4":"Value4"}

Answer 1

I see two different questions, I'll try and address both.

1. "Do they have to go out and upgrade themselves?". No they don't, you can push the upgrade: https://developer.salesforce.com/docs/atlas.en-us.packagingGuide.meta/packagingGuide/push_upgrade_intro.htm
2. "How do we make this backwards compatible?". Can't you maintain the old method for three input parameters and create a new one for four?

It's harder to give an answer without any specific code.

Answer 2

There are different ways to accomplish this.

First is versioning.
@RestResource(urlMapping = '/DemoEndpoint/v1/*')

By adding the v1 your end users can use the different versions and upgrade to newer versions when ready. The next version may be
@RestResource(urlMapping = '/DemoEndpoint/v2/*')

Versioning is recommended for API endpoints. You will need to create separate classes for each version.

The second method is to change how you accept the input parameters. In this scenario remove the input parameters in the method definition, and use Request.requestbody.

This is the original code (assuming you followed the developer guide example)
@HttpPost global static void myPostMethod(string Element1, string Element2, string Element3, string Element4)

New code accepting 3 or 4 parameters (or 0 parameters, see note below).

@HttpPost
global static string myPostMethod() {
    RestRequest request = RestContext.request;
    String body = request.requestBody.toString();
    List<Wrapper> obj = (List<Wrapper>) JSON.deserialize(body, List<Wrapper>.Class);

The wrapper class would be

public class Wrapper{
    string Element1;
    string Element2;
    string Element3;
    string Element4;
}

If Element4 is empty it was not passed in. Using this method you will need to do input validation. For example, this will accept zero parameters and all elements will be empty.