Versioned Endpoints

You may notice that the majority of the stock end metadata JSON files live in a folder named v1\, their exposed HTTP routes all have /v1/ in their path, but there is no 'v1' route segment in the route metadata. In order to help facilitate future releases of these end points, services supports automatic versioning of the routes. In the eBusiness\json\metadata\ folder if you create a folder that starts with 'v' and has only numbers for the rest of the name, services will automatically append a segment to the beginning of the route for the end points declared in that folder.

Will services automatically create any other segments?

No. Only folders in the format 'vNNNN' are supported, where 'NNNN' is a number. If you nest your end points in a different folder, like 'communityBrandsDemo\' it will have no effect on the routing. The exposed route will be exactly what you’ve defined in your route segments.

Can I disable automatic versioning?

Yes. A route block can have an optional attribute 'automaticallyIncludeVersioning'. The version segment will not be added if this attribute is set to false. You cannot disable this behavior globally for the entire application.

How does this help with future releases?

The intent is for future releases to create new versioned end points when additional functionality is added that would break existing integrations. For example, let's say in a future release Aptify decided the attendee creation end point /v1/Events/Attendees needed to require a phone number when creating a person in the system. Adding this requirement to the v1 end point would be a breaking change for any systems currently using it. To avoid this, the new end point would be deployed inside the a v2 folder, Aptify would automatically add the versioned segment to the route, and the existing end point would be unaffected. This could also be managed manually by explicitly adding a static 'v2' route to all new end points definitions but it seemed safer to have the framework automatically manage this for us.

Is versioning the end point all that is needed to avoid a break?

No. Care must also be taken in the business logic and process flows that execute. For example, if we were to add a new required parameter to the process flow that executes across the v1 and v2 end point, the v1 end point would break since it would not be requiring the new input from the caller.

How should I approach modifications to the stock end point metadata?

The recommended way is to create a new json file for what you are modifying by copying the original. In the above example, you can copy EventsEndpoint.json to EventsEndpoint__c.json and make your modifications in the new file. You should also rename the original EventsEndpoint.json to a different file extension to disable the original end points. By having two copies of the file, you can still compare against stock to get an understanding of what you've changed.