We are in a situation where we have pages of the news template type, that can carry any number of nodes of the news_item template type. In effect they should only ever carry nodes of that type and that type alone, and nodes of the news_item type should only be created under nodes of the news type. Thus, the "available templates" for a user when he/she tries to create new content under a news node should only be a news_item.
Is it possible to enforce this somewhere? For instance as some kind of attribute in the news_item and news xml files?
Currently that's not possible. There is quite an old issue on github describing that, but it had never a high enough priority for us to implement it.
Related
I am in the middle of developing my first Hypermedia API. I thought I had a good grasp of things but when It comes to documenting the API, I start to question my understanding of the whole concept.
The core of the question comes down to documention, but It might be that I did not understand one or more aspects correctly. If so, please tell me :-)
Documenting Link Relations
Let's say I have a more or less generic link relation (https://example.com/rels/accounts) in my API to link related accounts. The exact meaning can change on context, right?
On my billboard (or index), I might have a link with that relation to browse all accounts.
On another resource, account group for example, it might just link to a specific subset of accounts belonging to that group.
How should I document that relation? Just saying that this is a link to a collection of accounts seems not enough. However, that is exactly what RFC5988 does, just describing what the link itself means. So that might be the way to go.
The problem gets worse with actual state transitions. Let's use https://example.com/rels/create-account as our example here. If the documentation just says "This is where you create a new account", It makes no statements on what I have to do with that link to create a resource. Where would the documentation be that states something along the lines:
You either POST multipart/form-data or application/json to this endpoint that contains at least the following fields [...]
The relation itself does not seem to be the right place. Especially when you consider that the payload to that URL might also change on context. In our example, having that relation on an account group would make it mandatory to omit the accountGroup field because the value is provided by the context.
Documenting Profiles
As far as I understood it, I can (and probably should) have a profile for each resource in my API, documenting the resource itself. This would include its properties and links that can occur. Would that be the place where I specify what the link means exactly?
Sticking to my earlier example, would I document for profile https://example.com/profiles/account-group that the link with the relation https://example.com/rels/accounts links to a collection of accounts that are part of this group?
That makes sense to me, but when we go into actual state transitions things seem to get messy.
State transitions
Let's say the client navigated to an account collection from an account group. The resource itself would not really differ from the resource that contains all global accounts. It would have pagination links and the links to the account resources themselves.
If that account-collection resource has a link with the relation type https://example.com/rel/create-account I would be in deep trouble, right? Because the information that this is an account-collection containing just accounts of a certain group is not encoded in the profile
https://example.com/profiles/account-collection and can therefore not contain the information that clients have to omit the accountGroup property when posting to that resource.
Concrete Questions
Am I right that relations definitions should be weak and not contain any information about how I can interact with the resource it links to?
If so, can I expect from client to follow a link and then discover what they can do, based on the profile of that resource. This seems wrong, especially for state transitions.
If profiles should document what a client might do with the linked resources, I cannot transport context across multiple "jumps" within the API, correct?
Should I use even more profiles and relations? https://example.com/profiles/global-accounts and https://example.com/profiles/account-group-accounts come to mind.
The more I think about it, I must either miss a critical piece or it's something that can be solved in multiple ways. Because of that, I am aware that there might be no 100%-correct answer to this question. But maybe someone can enlighten me so that I can make my own trade-offs? :)
Let's take your points one at a time:
1. Link relation meaning based on context
To reformulate your question into code context: How do I document the "getAccounts()" method when it means something different in the class Billboard and AccountGroup?
The obvious answer is you don't document the method in general, but you document the classes and within them the methods. The RFC you're referring to tries to define relations that are in some sense generic, or should mean the same thing every time. You might re-use some of them, but you still have to document the method and what they mean in your class.
Class equals to your Media Type. So I propose you document your Media Type.
2. Links and Forms, how to define what to POST
If you document your Media-Types, you can define whatever you like in there, including how to use its links. However, I would recommend not defining the Media Type of the POST, but letting it up to Content-Negotiation.
The client knows it has to POST an Account, it will use some Media-Type it thinks is proper for this task. The server will then tell the client whether that format is acceptable or not, it can also give a list of acceptable Media Types in return.
3. Documenting Profiles
If by Profiles you mean Media-Types, then yes, you should document them. You should actually only document Media-Types.
4. State transitions, modifications to representations based on state
Since the account group is a resource anyway, the client should not actually supply it, it should be part of the "state" which group the new account belongs to.
In other words, the client gets a link, that already has the context of the current account group. The client has to post a generic account, but the server knows it should belong to the group in the current state (it is part of the URI for example)
So no, the client shouldn't know it has to omit some parameter.
5. Question
Yes, relations should not define how to interact with the resource. Media Types could actually do that (like Forms defining it must be a POST, etc.), but more often than not it's not necessary.
Yes, clients discover not only what transitions are available (links), but what methods are available. The methods (GET, POST, PUT) always mean the same thing, and they are not described in Media-Types, since Media-Types only describe representations, not resources. The server normally submits all the supported methods in a response, or explicitly in response to OPTIONS.
I still don't really know what you mean by "Profile". If you mean relation profile, as in some data in the link definition, then no. The context/state travels in the URI. You can use the URI to "save" that the client is moving inside one account group for example.
No, you shouldn't add semantics to link relations. The Media-Type adds the semantics to links.
HTH
I will try to answer more succinctly than Robert's answer, which I think can get confusing.
Let's say I have a more or less generic link relation (https://example.com/rels/accounts) in my API to link related accounts. The exact meaning can change on context, right?
No. The meaning of a link relation is static. Your "list of accounts" relation on your index (list of lists) page is specific to your application. In your other example, account group, you are already in a "collection" resource, and members of that collection have link relation "item" (see the list of IANA link relations).
The problem gets worse with actual state transitions. Let's use https://example.com/rels/create-account as our example here. If the documentation just says "This is where you create a new account"
I would instead add a "create-form" link (another standard IANA link relation) to the "list of accounts" page. Your clients would then go: start -> list-of-Xes -> create-form -> submit. There would be no "create-an-X" or "create-a-Y" link relations. You probably would not allow clients to create new collection types either. This makes navigating the API lengthier for clients but reduces the amount of stuff they need to know (API breadth).
Would [a profile] be the place where I specify what the link means exactly?
If you make your link relations generic except for one to describe each model class, you will not have to document these in profiles on a per-model-class basis.
If that account-collection resource has a link with the relation type https://example.com/rel/create-account I would be in deep trouble, right?
Yes, so don't do that! What you are describing there is linking an existing resource to a collection (by IANA's definition). What I would advise is that you support clients being able to do this:
LINK http://site/account-collections/some-collection HTTP/1.1
Link: <http://site/accounts/some-account-id>; rel=item
Authorization: Token abc123
This simple (complete!) HTTP request has the semantics of adding an "item" link containing the existing account's URI to the collection you wish to add it to. It does not create a new account. The LINK method is still in draft but has existed in some form since HTTP 1.1 (1997).
Robert wrote:
You should actually only document Media-Types.
I disagree. You should document link relations too, but try not to create them if you can use an generic one.
I am currently setting up Schema.org content on multiple sites.
They are using the LocalBusiness type and have telephone/address both in the header and footer.
When setting up Schema.org on both sections and testing, I get 2 LocalBusiness returned with the same content.
Does this affect in any way the Schema.org? Would it be better to only have it pull 1 section instead of 2?
With Microdata/RDFa, you are not annotating your page’s content. You are just using your content/markup as "carrier" to provide structured data.
If the telephone number of the local business appears several times on the same page, there’s no need to mark it up with Microdata/RDFa several times: you only need it one time for the consumers that make use of your structured data.
So don’t provide two LocalBusiness items on the same page, if both really represent the same local business.
In cq we can create live copies by either blueprints by opting "New Site..." or directly trough content nodes by opting for "New Live Copy...".
In both the cases inheritance is maintained and roll-out works too in same ways. So what is the advantage of using one over other.
Any views?
Live Copies
Live copies can be created for just a simple page or a tree of pages and might the page and it's subpages depending on the rollout configuration. A live copy can be linked to a rollout config or will use the system's default one.
There is no formal requirement on the source page's structure.
A live copy might reference a blueprint, while it can only reference to a single blueprint.
Blueprints
Blueprints target the rollout of complete multilingual website projects and are a tool to control multiple rollout configs and live copies.
A blueprint requires a certain structure for the source site:
- One root level page
- The root's immediate childs define the language branches of the site
- each language contains one or more child pages.
Blueprints allow you to control multiple live copies and centrally consistent rollout configs for the blueprint's live copies.
A blueprint rollout will push modifications to all it's live copies.
Usage scenarios of blueprints
Inheritance and rollout work the same way. Just because blueprint make use of live copies.
But blueprints help you to organize your rollout scenarios for large multilingual sites. Just imagine a corporate website that provides a two or even three digit number of locales which that need to be translated and kept in sync.
In such a scenario you will likely end up with a hardly understandable and maintainable number of live copy and rollout configurations.
Depending on a blueprint to e.g. standardize the rollout of a new language/market/locale provides you higher degree of governance over your process as the complete process centrally manageable through the blueprint template.
But as long as you do not have such a scenario you might be fine without having the complete blueprint overhead.
A Livecopy is defined in the target page node with a cq:LiveSyncConfig node. It basically defines: I am a livecopy of source (blueprint) page X, and the following rollout configs apply.
A Blueprint is defined in the source page node with a cq:BlueprintSyncConfig node, and this defines a target.
Essentially both achieve the same in the end, but I think there are a few differences: the first option can be used to create a 1:n relationship, whereas the second option is 1:1
Also, if page nodes are copy-pasted in AEM, then relationships are copied with them (not quite sure in which way exactly, you would have to try for both scenarios). Also when pages are deleted in a tree in the first scenario, AEM will add a cq:excludedPaths property to the config which causes the page to be skipped in future rollouts - not sure this is the same for cq:BlueprintSyncConfig as well.
Currently I am building a site with a Facebook Open Graph integration.
One complication I have is since user can do seemingly similar actions to different objects on our site, it is easy for us to define different action for each similar actions. However, it seems like Facebook is not allowing ( or at least not liking ) for one site to have multiple similarly looking actions.
For instance, let's assume that user can both 'buy' a car, and 'buy' an insurance in our site.
Although, on surface, these two action look similar, because their context is different we want to show different content - more specifically different caption - for each action that is postsed.
Simple way to implement this will be defining two actions,
'BuyCar' <---> associated with Car
'BuyInsurance' <---> associated with Insurance
and let them have distinctive caption template.
However, as I mentioned earlier, since Facebook does not allow multiple similar actions to be defined within a site, I should be defining.
'Buy' <----> associated with [Car, Insurance]
where this action always have only one property defined. (either Car or Insurance)
Downside of having these type of action is, due to limitation in current cation's template language (lacks conditional statement), I am not able to produce different caption effectively without knowing which property is set.
How should I be handling this issue?
Your help will be greatly appreciated.
Thanks
I think the captions do need to be something generic that will work for all connected object types. But you could use filters to defined separate aggregations for each object type.
Just add an additional parameter to all of your objects and set the value of that parameter as an aggregation filter?
I have a client-side interface that allows the user to perform multiple edits against a tree-like outline. I consider the aggregate of the records making up that outline, in totality, a single resource (/outlines/39) even though its parts could be accessed as separate resources via different URLs.
The problem is the user can edit existing nodes in the outline as well as add new nodes to the outline. Normally, when you edit something you PUT its changes and when you add something new you POST it; however, in some cases you'll want to wrap all the changes--including both adds and edits--in a single transaction. What are some practical ways people have handled this?
Even though the outline already exists and a PUT seems appropriate, the embedded adds violate the idempotence of the PUT. I'm not sure that POST seems appropriate either. For design purposes, I have decided not to save each discrete update the user makes though I guess this offers one solution. Still, there must be others who have dealt with my issue or have ideas about it.
Is there any way you could make the add idempotent? E.g. if nodes had a natural key, then when the client tried to add a node a second time you could do nothing.
How about: make a new resource: /outlines/39/transactions, and POST your transaction to that resource, e.g.
POST "addNode=node1, addNode=node2, editNode=node3,newName=foobar" to /outlines/39/transactions