link resolution + json serialization

[kylemac]

two points but i think they are fairly interconnected so i've only filed one issue.

link resolution

it appears that there is partial support for this in the library but it's not documented. since all of your site's json gets returned from one API call this shouldn't be hard to do either. are you open to the idea of adding an option that would do nested resolution from within this client so that we don't have to traverse our objects for each implementation of the client? ideally this would look like contentful.js' option but could also be part of .get() or .all() functions. in practice all anyone ever wants is their fully resolved data so i could even imagine this option is true by default.

json serialization

while looking for this link resolution functionality i came across src/local/Loader.js which I think does link resolution but returns a class object with no ability to serialize this to json. the assumption here is so that it would avoid circular references that might happen if it were json. as part of the link resolution request, it makes sense that some kind of smart json serialization that avoids the infinite loops.

this seems like an extremely common use case and we've avoided filing this issue in the past because we've done our own link resolution within our spike-datocms plugin, but imo this really should be handled by the client

cc @jescalan

[stefanoverna]

Ok, so I'll start trying describe the current state of this package. As you have correctly guessed, our (JS and Ruby) clients have two different ways of interacting with DatoCMS API.

The first (SiteClient) is an extremely thin layer over our REST API endpoints (https://www.datocms.com/api/), it lets you do things like creating a record. It accepts simple plain old JS object as input, and returns simple plain old JS objects as output.

import { SiteClient } from 'datocms-client';

const client = new SiteClient("YOUR-API-KEY");
const article = await client.items.create({ itemType: "44", content: "Lorem ipsum dolor sit amet..." });

The second one (Loader), is meant to be used in the context of building a static website, so it's read-only, and it basically loads every content present in an administrative area and returns an ItemsRepo object that offers any kind of helper methods to easily query your content, with link resolution and everything:

import { SiteClient, Loader } from 'datocms-client';

const client = new SiteClient("YOUR-API-KEY");
const loader = new Loader(client);
await loader.load();

loader.itemsRepo.articles[0].author.avatarImage.url();

While this ItemsRepo class is not explicitly documented anywhere, basically it's the dato argument you get when using our CLI tool.

[stefanoverna]

Now, if the need is to find a good way of integrating DatoCMS with Spike, I would suggest you not trying to reinvent the wheel and directly offer to your users an ItemsRepo instance. I already talked to @jescalan in the past about this, even tried to work on a PR but got stuck :)

I'll copy the conversation here:

Regarding the spike-datocms plugin, I've made some progress:

• Here's the proposed changes: static-dev/spike-datocms@master...datocms:master
• And here's an example of usage: https://github.com/stefanoverna/spike-datocms-example/blob/master/app.js

The main changes:

• Remove the API parsing logic from spike-datocms, reuse the datocms-client ItemsRepo for that (static-dev/spike-datocms@master...datocms:master#diff-6d186b954a58d5bb740f73d84fe39073R44). This means that in the views you can access to every content stored in the DatoCMS backend in exactly the same way as you would do in a dato.config.js file using our dato dump command.
• Change the way you declare single pages in app.js: https://github.com/stefanoverna/spike-datocms-example/blob/master/app.js#L29-L33
• Introduce a dato-meta-tags directive that you can use in your views to populate the of your page (a similar thing should be made to generate favicon meta tags)

That's just a proof-of-concept.. sure there are better ways to code the whole thing, but that's the interface I would suggest to the outer world.

[kylemac]

@stefanoverna awesome, thanks for providing more info about the Loader! i'll go back and play around with it and see if it exposes everything we need.

As for spike + dato, I guess I should say that I was not explicitly filing this issue to support spike-dato, I was just using it as a known reference. At the moment, I'm actually doing a non-spike implementation which was why link-resolution was so important to me bc I didn't have the link resolution available to me thats part of spike-dato.

Anyways, I'll do a bit more digging on how the Loader can be used now that, in lieu of some docs, you've cleared up the basics.

[stefanoverna]

Ok, let me know if you got everything you need :)

[kylemac]

@stefanoverna do these functions create another network call to the API or just traverse the object from the original API response?

[stefanoverna]

Only two API calls gets made during the loader.load() call then everything else is handled locally using that data.

[stefanoverna]

Just to make clear: here we try to keep things simple and manageable, and for our initial use case (static websites) the current solution — that is, having a limited API, fetch everything during the build phase and then offer a handy interface for querying with the ItemsRepo — works fine.

This obviously doesn't work as well when you simply cannot afford to download everything (ie. client-side apps, server-side apps, mobile apps, etc). We've in the roadmap to add read-only GraphQL API with advanced querying functionality for that in the near future, but for now.. that's what we offer :P

[kylemac]

yup, understood. i personally like the big API response bc it lets me cache my data locally easily but obviously it limits folks with huge datasets or client-side requirements. thanks for sharing roadmap info, stefano