Our main goal for the ACP Composer API is to provide the consumers with what we call Presentation-friendly content. This means that you should be able to parse and present our content easily and with as little effort as possible. However, this is a an content API. And we need to keep some sort of structure in our data as well. There is a certain level of complexity that it is hard, or even impossible, to hide from the consumers.
This is an overview of what we mean by Presentation-friendly
In a typical RESTful approach, relations would just be links to other objects in the API. However, this would require the consumers to send a lot of HTTP requests to the API just in order to collect enough data to present a single article or search result. By using the _embedded features in the HAL-specification we are able to reduce the number of requests required. Since it allows us to provide you with, what we have defined, the needed information/data from all the relations/teasers.
Reducing the number of requests required is our main concern.
We have to admit that this is our Achilles heel right now. When reading a value from an object field you don’t know whether the value is a plain text string, a html string, a boolean, a number or a date. It is normally easy to guess from the values itself, but not always.
Should the title in the example above be encoded as HTML before use, or printed as plain text? You just don’t know right now. If you don’t encode the title value, you might run into trouble next time when the title is changed to…
You get the point :) Introducing field types is something we are working on, and will introduce soon.
In the mean time you should follow these rules:
- All fields named leadText and Body are HTML out of ACP and should be treated as such.
- All other text fields are plain text and should be encoded before used inside a HTML/XML context.
All links inside the API should be full URLs. And not relative URLs. Consumers that have been around for a while knows that this haven’t always been the case. Specially for image URLs. But we promise to stay away from relative URLs from now on. Or at least to always provide a full url for all resources. Some relative urls will stick around for a while until they are deprecated and removed.