How Prismic.Api() is supposed to used ? (lifecycle)

[dlecan]

From the documentation, I can see:

Prismic.Api('https://lesbonneschoses.prismic.io/api', function (err, Api) {
   ...
}); 

to make a request to my Prismic repository.

What is the best way to use it to make several requests?

Solution 1:

Prismic.Api('https://lesbonneschoses.prismic.io/api', function (err, Api) {
    // 1st request
    // 2nd request
    ...
    // nth request
}); 

Api instance is the same for all requests, which may be an issue when repository is updated between all requests. Sometimes, api must be requested again to update current Prismic's ref.

Solution 2:

Prismic.Api('https://lesbonneschoses.prismic.io/api', function (err, Api) {
    // 1st request
}); 
Prismic.Api('https://lesbonneschoses.prismic.io/api', function (err, Api) {
    // 2nd request
}); 
...
Prismic.Api('https://lesbonneschoses.prismic.io/api', function (err, Api) {
    // nth request
}); 

Api is requested first for all search request. No problem when Prismic repository is updated during requests, but this costs 1 extra request to API for each search request.

I have seen an apiCache in the JS Kit, with a 5s time-to-live. But I don't understand how to use it. In "solution 1", this cache seems useless as only Prismic.Api call is checking the cache and there is only one Prismic.Api call. In "solution 2", this cache seems useless again as each Prismic.Api create an instance of ApiCache, which is not shared between Prismic.Api calls. And "ApiCache" implementation seems to be private, so I can't give my own instance to Prismic.Api calls.

So what's the best way to use Prismic.Api? Thank you

[erwan]

Hi,

What's your use-case? The Javascript kit can be used in-browser, or server-side with NodeJS. Depending which way you're using it, there can be differences on the way it's used.

Solution 1 is perfectly fine. You shouldn't worry about retrieving older content, because the code you have inside your block is not supposed to take such a long time. Additionally, it's better to have all your requests performed on the same release because otherwise you can get inconsistencies (ex: link to a document that was deleted in a newer release).

When a new release is available, the older reference stays available with the "master only" token for 5 minutes. If your block takes longer than that, you should consider using a token giving access to all releases.

For solution 2 I think you're right, the cache won't be used. I'll take a look and see how I can improve it. In the meantime the implementation is pretty simple and only 50 lines long, feel free to fork it to pass it to Api.get: https://github.com/prismicio/javascript-kit/blob/master/src/api.js#L678

One last thing: if you need to do several calls, it's recommended for better performances to do them in parallel. That can be done more easily with promises: http://documentup.com/kriskowal/q/

Since the Prismic.io kit functions follow the Node.js pattern, you can adapt the submit call to a promise like any Node.js asynchronous call:

function Q_submit(form) { return Q.nbind(form.submit, form)(); }

[erwan]

I've just pushed version 1.1.3 of the JS kit, now the cache object is shared between all API instances.

[dlecan]

Thank you for your answer and your advices.

What's your use-case?

In browser mode.

When a new release is available, the older reference stays available with the "master only" token for 5 minutes

Useful information, so Api cache can be longer than 5s :) Thank you for the quick release.