What is the REST API and why should I use it?

In this blog post, I like to introduce you to Episerver Campaign's latest Application Programming Interface (API) following the modern architectural style of Representational State Transfer (REST). I will show you its advantages over our traditional HTTP mail/form and SOAP web services as well as give you some tips to quickly get started.

RESTful web services are based on the principles and behavior of the World Wide Web. They enable consumers to access and manipulate textual representations of web resources using a standardized set of stateless operations (HTTP methods). Responses contain status information about the outcome of request processing (e.g. they can confirm state modifications to a resource or indicate non-existing resources or processing errors) which also follow internet standards, see the Internet Engineering Task Force (IETF) RFCs 7230-7235.

Advantages of the REST API

In addition to its simplicity, ease of use and great interoperability which increase the development and integration productivity, the REST API also brings the following advantages:

• Support of other data formats than XML; we use the more compact JSON by default
• JSON results in faster parsing, less network bandwidth usage and offers better support of browser clients (e.g. JavaScript)
• Superior performance, particularly through caching of information that is not altered and not dynamic
• More scalable (e.g. no use of sessions)
• Simple and dynamic documentation based on the OpenAPI specification supporting convenient features like "Try it out" (see below)

Therefore, we focus our own development efforts on the REST API. Existing features of our HTTP and SOAP APIs are continuously integrated in our REST API. Newer features like Smart Campaigns are only available in the REST API. You can find a list of all currently available endpoints in our resource documentation.

Tips for working with the Episerver Campaign REST API

To use the REST API, you need an Episerver Campaign client set up for this purpose, and an API user with credentials to authenticate. Once set up, you can test and use the REST API either directly from our resource documentation using the "Try it out" feature or using any HTTP/REST client of your choice like Postman, Insomnia, Paw or the command-line tool CURL.

Each REST API endpoint URL is built according to the following schema: https://api.campaign.episerver.net/rest/{clientId}/{component}/{path}?{parameters}.

The "clientID" parameter is the ID of your client in which the REST API has been set up and represents the root element of each endpoint. You can find the client ID in Episerver Campaign under Administration > API overview > REST API.

When performing API calls, you receive response status codes for each request. In addition to the response status code, you should always process an existing response body to either retrieve the representation of the resource or additional information about business errors.

Try it out and share your experience

Please feel free to use the REST API and integrate Episerver Campaign's rich functionality into your system or develop your own solution!

You are also welcome to check the Episerver Campaign blog from time to time - there will be more posts about the REST API, new features, and endpoints in the future.

If you like, you can also blog yourself or discuss APIs and integrations with other developers in the Episerver Campaign forum.