Campaign has schemas to describe every piece of data. For instance recipients have a schema : nms:recipient. Even Schemas have their own schema (xtk:schema). A Campaign schema is more than just a description of the data, the available properties of an entity and their types. Campaign schemas are really similar to classes in an object model: they describe the data of course, but they also contain methods which will be made available automatically as SOAP APIs. Schemas also support an inheritance mechanism, including the notion of interface. An interface is simply a descrption of one or several methods. Schemas inheriting the interface will inherit their methods.
Campaign SOAP APIs are not REST APIs. Not only, we're using SOAP and XML, but Campaign also uses a very different model for APIs. In fact we use a object oriented model, i.e. APIs in Campaign are closer to remote methods invocation than REST APIs are. For instance, imagine what a REST API call to retreive a profile would look like. You'll probably issue a GET operation on the profile resource with a more or less sophisticated mechanism to filter the selected profile based on query parameters.
In Campaign, you'll execute a query. You are going to use the ExecuteQuery method of the xtk:queryDef schema. This API actually directly matches the method VExecuteQuery of the XtkQueryDef class of the C++ code.
<srcSchema namespace="xtk" name="queryDef" implements="xtk:persist"> <element name="queryDef" pkgStatus="never">...</element> <methods async="true"> <method name="ExecuteQuery" const="true"> <parameters> <param desc="Output XML document" name="output" type="DOMDocument" inout="out"/> </parameters> </method> ... </methods> </srcSchema>
This is the xtk:queryDef source schema, which defines the ExecuteQuery method
To name APIs, we use the convention {schemaId}#{methodName}. For instance, the ExecuteQuery method of the xtk:queryDef schema is named by its URN: xtk:queryDef#ExecuteQuery. The URN is an important concept and is passed to every SOAP call through the SOAPAction HTTP header.
Sometimes, methods which are inherited from an interface. For example the Write method is defined in the xtk:persist interface which is implemented by the xtk:session schema. For such methods, the URN is xkt:persist|xtk:session#Write, where we have both the interface id and the schema id separated by a pipe character.
<srcSchema namespace="xtk" name="queryDef" implements="xtk:persist">
...
</srcSchema>
Thee xtk:queryDef inherits the xtk:persist interface
Regarding schema inheritance, it is possible to define custom methods in derived schemas. For example, a customer may extend the nms:recipient schema with an extension schema named cus:recipient, and may declare one or more custom methods in this extension schema. Such methods will of course be exposed as SOAP APIs, but they are available on the base schema only, i.e. on nms:recipient and not on cus:recipipent. The reason for this is that Campaign actually merges all the schemas and their extensions (which we all call source schemas, by the way) into the actual schema which takes the name of the base source schema. As a consequence, the SDK actually always deal with schemas, and not source schemas, although it is also possible to handle source schemas by calling the appropriate APIs.
The SDK works with the underlying notion of representation. Internally, Campaign uses XML to represent all entities. Using XML is fine, but nowadays, people find it complicated and verbose and prefer to use JSON.
The SDK is able to handle both XML and JSON representation for Campagin objects. It defaults to JSON, which means you pass JSON objects to the SDK and it returns JSON objects, and takes care of the JSON <=> XML conversion automatically. The SDK is not limited to JSON, but can use XML instead (DOM API) if you change the representation.
3 type of representation are handled by the SDK
To understand the challenges and pitfalls of XML to JSON conversion, follow this link
To know more about the SimpleJson representation, follow this link
To better understand how Campaign deals with XML and use helpers to simplify your code, follow this link
To know more about the BadgerFishs representation, follow this link
The JS SDK provides an asynchronous API, which means most of the functions return promises. In particular, many functions in the Application API return promises.
This is an important difference between the SDK and Campaign. The reason is that the JavaScript which runs inside Campaign is running server side and is synchronous. The SDK however, is running outside of Campaign and needs to be able to wait for the result of API calls.
To understand the differences between the JS SDK and Campaign JS, follow this link