Introducing Custom API preview
Common Data Service has had the Custom Action feature for many years. Custom Actions provide a no-code way to create a new API that can be called from CDS web services.
Custom API is a new code-first approach that extends the concept of Custom Actions to provide capabilities that will make life easier for developers.
Custom Actions depend on workflow to allow anyone to compose a set of logic using a designer without writing code. This is a great capability, but it is no secret that developers have been leveraging Custom Actions to create new APIs and ignore the designer. Rather than implement their logic with the designer with workflow, they have been using this capability to create APIs and then register plug-ins to apply their logic in a way that is most productive for them. This enables them to do things workflow can’t do.
Custom API is acknowledging this pattern and making it easier for developers to use. With Custom API, there is no workflow and some of the limitations of Custom Actions can be avoided providing new capabilities for developers. Instead, Custom APIs require that the developer create a plug-in which will provide the main operation for the message.
This is a preview feature and some of the planned experience isn’t fully complete. Some areas are still subject to change and we have a list of known issues. But developers should have everything they need to start using this new feature.
The following is a list of some of the capabilities enabled with Custom API:
Define your Custom API using solution files
Developers who follow Application Lifecycle Management (ALM) practices work with solutions by extracting them and storing them in a source code repository. With Custom API you can compose your messages using folders and xml files directly in your solution.
This isn’t the only way to create new Custom APIs. There is a UI where you can enter data in a form, and you can also use our API to create new Custom APIs.
In the future, we intend that the Custom Action designer will include options to create Custom API in a unified way.
Set a specific privilege
If you want to block someone from using your Custom API unless they have a specific privilege, you can specify the privilege so that a standard privilege error will be returned before it hits your code. You will not have to include code to check for this privilege.
New input and output parameter types
While we are starting out with the same set of input and output parameter types that Custom Actions support, we intend to add some new types very soon: List<string> and Guid. Because Custom API is not bound by what workflow supports, we can provide additional options for greater flexibility when you compose your APIs. Which additional types do you need?
Block extensions by other plug-ins
Custom Actions allow developers to register plug-ins on any of the available stages. This is what enables developers to use plug-in logic for custom actions rather than the workflow logic. But this also means that any other developer can apply their own logic before or after your logic, potentially changing the behavior of your API. Sometimes that is a good thing, but as the API author, you should be able to make the decisions about whether to allow this or not. With Custom API you can decide whether 3rd party plug-ins can be registered for other stages at all, or perhaps only for asynchronous steps.
Make your message private
When you use a Custom Action to define an API, it is always public. This means that anyone using the Web API $metadata service document may discover it and try to use it. As the author of the API, you won’t know whether someone else is using your API. But if you remove it, or introduce some breaking change, anyone else who is using your API will be broken.
If you are creating an API and don’t intend for anyone else to use it, mark it as private. This is how you can say that you don’t support anyone else using it. This will block the API from being advertised in the Web API $metadata service document and people using code generation tools with the Organization Service will not be able to generate helper classes for it. This is the same method used by Microsoft to separate internal private messages from the public ones.
Create an OData Function
The CDS Web API is an OData web service. OData provides for two types of operations: Actions & Functions.
- An Action is an operation that makes changes to data in the system. It is invoked using the Http POST method and parameters are passed in the body of the request.
- A Function is an operation that makes no change to data, for example an operation that simply retrieves data. It is invoked using an Http GET method and the parameters are passed in the URL of the request
There is nothing to prevent you from defining all operations as Actions if you wish. But some operations may be best expressed using a GET request available by defining a function.
Localizable Names and Descriptions
While Custom Actions provide for a friendly name for the custom action and any input and output parameters it uses, these values are not localizable. With Custom API you can provide localizable names and descriptions. These localized strings can then be bound to controls that provide a UI to use the message.
Next steps
Please review the documentation and try this new feature. Let us know what you think.