Create a Custom API in the maker portal

The current experience creating Custom API within the maker portal is temporary. We intend to provide a modern experience in the future.

Important

Many fields related to creating Custom API cannot be changed after you create them. You should carefully plan the design of the Custom API before you start. If you later decide that you need to change things after you create the Custom API, you may need to delete the existing record and re-create the Custom API.

Please review the following to understand which field values cannot be changed:

When creating a Custom API it is expected that you will use a solution. Your solution must be associated with a publisher. The publisher will have a specific customization prefix associated with it. You must use a customization prefix when creating a Custom API and this prefix should be the same used by the publisher of your solution. The instructions below will use the value sample as the customization prefix because it is the one set for the following publisher:

Solution publisher with sample prefix.

Note

This topic assumes you are familar with solutions. If you are not, see Create a solution

Create a Custom API record

  1. In your solution, click New and select Custom API from the drop-down.

  2. Edit the fields to set the properties of your Custom API. You must set values for the following fields. For more information see CustomAPI Table Columns

    You cannot set values for Plug-in Type unless you have already created the plug-in. You can change this later.

  3. Click Save. Your form should look something like this: Saved Custom API form.

Note

If you delete the Custom API record, all request parameters and response properties will be deleted with it. Make sure that the Custom API field values are correct before proceeding. Otherwise you may need to repeat all of these steps to re-create your Custom API if you need to delete it.

We recommend that you set the IsCustomizable managed property to false for all Custom API components. This property is not available in the form. For more information see Managed properties

Create any Request Parameters

A Custom API doesn't require parameters. Create as many parameters as you need to pass data needed for your logic.

Note

If you define a bound entity for your Custom API action, the parameter will be generated for you. You don’t need to create an input parameter for the entity when the Custom API is bound to an entity.

If you bind your Custom API action to an entity collection, there will not be a parameter generated for you. Binding a Custom API action to an entity collection requires that the Custom API be called using the entityset resource path.

Binding to an entity collection only sets the expectation that the operation will be performed on more than one entity of that type or that it will return a collection of that type. It does not provide an entity collection input parameter for your plug-in to process.

  1. In your solution, click New and select Custom API Request Parameter from the drop-down.

  2. Edit the fields to set the properties of your Custom API Request Parameter. For more information see CustomAPIRequestParameter Table Columns

  3. Click Save. Your form should look something like this:

    Example of a Custom API Request Parameter Form.

Note

As noted earlier, we recommend that you set the IsCustomizable managed property to false for all Custom API components. This property is not available in the form. For more information see Managed properties

Create any Response Properties

A Custom API that represents an action doesn't require response properties. If the operation succeeds, it will return a success response. If it fails, it will return an error. You should define response properties for any data that your API will return.

Important

A Custom API that represents a function requires at least one response property to be valid.

If there is only a single Entity or EntityCollection response property defined, the response will be of that type. If there are multiple properties, or one or more property of a simple type, the API will return a complex type where each response property will be a property of that complex type.

For example, if your Custom API Unique name is sample_CustomAPIExample, it will return a complex type named sample_CustomAPIExampleResponse with properties for each response property you define.

  1. In your solution, click New and select Custom API Response Property from the drop-down.

  2. Edit the fields to set the properties of your Custom API Response Property. For more information see CustomAPIResponseProperty Table Columns

  3. Click Save. Your form should look something like this:

    Custom API Response Property Form.

Note

As noted earlier, we recommend that you set the IsCustomizable managed property to false for all Custom API components. This property is not available in the form. For more information see Managed properties

Observe the result in the service document

If you haven't set the IsPrivate property for your Custom API, you can now retrieve the service definition from the CSDL $metadata document using a GET request, even from your browser. If the url for your environment is https://yourorg.crm.dynamics.com, you can type this URL in your browser address field to retrieve the $metadata: https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata.

Search the result to find the name of the Custom API. For example, the API defined using the steps above looks like this:

<ComplexType Name="sample_CustomAPIExampleResponse">
    <Property Name="StringProperty" Type="Edm.String" Unicode="false" />
</ComplexType>
<Action Name="sample_CustomAPIExample">
    <Parameter Name="StringParameter" Type="Edm.String" Nullable="false" Unicode="false" />
    <ReturnType Type="mscrm.sample_CustomAPIExampleResponse" Nullable="false" />
</Action>

If you have set the IsPrivate property for your Custom API, you won't find your custom API in the results. But you can set the IsPrivate value back to false and retrieve the $metadata again. The API will work exactly the same whether it is returned by the $metadata or not. You can always set it back to true before you ship your solution if you don't want to support others using your Custom API.

Test your Custom API

Now that you have created your Custom API you can try it. Even if you haven't set a plug-in type to define the main operation, you can test it now to verify that you can call it correctly. Any response properties will return their default value, such as null. More information: Invoking Custom APIs.

Update the Custom API Type

For information about how to write a plug-in for a custom api, see Write a Plug-in for your Custom API.

After you have registered your assembly, you need to set the Type value for the Custom API you created. This is a lookup property, so you just need to find the Plug-in Type that represents the type created when you registered the assembly.

Set the Custom API Type Lookup.

Once you have set the Type, you can test your Custom API to verify the correct results are returned.

Other ways to create Custom APIs

You may have requirements to create a client application which will allow creation of Custom APIs outside of the designer. Because the data for Custom APIs is stored in tables, you can create them using code. More information: Create a Custom API with code.

Your ALM process may be better served by creating Custom APIs by editing solution files. More information: Create a Custom API with solution files.

See also

Create and use Custom APIs
Create a Custom API with code
Create a Custom API with solution files
Create your own messages