io.prismic

Class Api

java.lang.Object

io.prismic.Api

public class Api
extends Object

Embodies an API endpoint, from which it is possible to make queries. This object should be instantiated once per webpage on your project, at the very beginning of the webpage, and then used for every subsequent document query.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Api.ApiData
static class	Api.Error

Constructor Summary

Constructors

Constructor and Description
Api(Api.ApiData apiData, String accessToken, Cache cache, Logger logger, Proxy proxy) Deprecated.
Api(Api.ApiData apiData, String accessToken, String defaultReference, Cache cache, Logger logger, Proxy proxy) Constructor to build a proper Api object.

Method Summary

Modifier and Type	Method and Description
static Api	get(String url) Entry point to get an Api object.
static Api	get(String url, Cache cache, Logger logger)
static Api	get(String url, String accessToken) Entry point to get an Api object.
static Api	get(String endpoint, String accessToken, Cache cache, Logger logger)
static Api	get(String url, String accessToken, String defaultReference) Entry point to get an Api object.
static Api	get(String endpoint, String accessToken, String defaultReference, Cache cache, Logger logger) Entry point to get an Api object.
static Api	get(String endpoint, String accessToken, String defaultReference, Cache cache, Logger logger, Proxy proxy) Entry point to get an Api object.
String	getAccessToken()
Document	getBookmark(String bookmark)
Document	getBookmark(String bookmark, String ref)
Map<String,String>	getBookmarks() From a properly built Api object, returns the map associating the bookmark names to their document IDs.
Document	getByID(String documentId) Retrieve a document by its ID on the master reference
Document	getByID(String documentId, String ref) Retrieve a document by its ID on the given reference
Document	getByID(String documentId, String ref, String lang) Retrieve a document by its ID on the given reference in the given language
Form.SearchForm	getByIDs(Iterable<String> ids) Retrieve multiple documents from their ids
Form.SearchForm	getByIDs(Iterable<String> ids, String ref) Retrieve multiple documents from their ids on the given ref
Form.SearchForm	getByIDs(Iterable<String> ids, String ref, String lang) Retrieve multiple documents from their ids on the given ref in the given language
Document	getByUID(String documentType, String documentUID) Retrieve a document by its UID on the master reference
Document	getByUID(String documentType, String documentUID, String ref) Retrieve a document by its UID on the given reference
Document	getByUID(String documentType, String documentUID, String ref, String lang) Retrieve a document by its UID on the given reference in the given language
Cache	getCache()
Experiments	getExperiments() Return the current experiments on the repository
Form.SearchForm	getForm(String form) From a properly built Api object, return a Form object that will allow to perform queries.
Map<String,String>	getFormNames() From a properly built Api object, returns the Map of available form names.
Logger	getLogger()
Ref	getMaster() From a properly built Api object, returns the ref ID (points in a prismic.io repository's timeline, whether in the past, in the present, or in the future) of the master ref (the one presently live).
String	getOAuthInitiateEndpoint()
String	getOAuthTokenEndpoint()
Proxy	getProxy()
Ref	getRef(String label) From a properly built Api object, returns the ref with the corresponding label
List<Ref>	getRefs() From a properly built Api object, returns the ref IDs (points in a prismic.io repository's timeline, whether in the past, in the present, or in the future) to which the passed credentials give access.
List<String>	getTags() From a properly built Api object, returns the list of available tags.
Map<String,String>	getTypes() From a properly built Api object, returns the map associating the type names to their readable text.
static String	getVersion()
String	previewSession(String token, LinkResolver linkResolver, String defaultUrl, Proxy proxy) Return the URL to display a given preview
Form.SearchForm	query() Start a query defaulting on the master reference (you can still override it)
Form.SearchForm	query(Predicate... predicates) Start a query defaulting on the master reference (you can still override it)
Form.SearchForm	query(String q) Start a query defaulting on the master reference (you can still override it)
Document	queryFirst(Predicate p) Return the first document matching the predicate on the master reference
Document	queryFirst(Predicate p, String ref) Return the first document matching the predicate on the given reference
Document	queryFirst(Predicate p, String ref, String lang) Return the first document matching the predicate on the given ref in the given language

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Api

public Api(Api.ApiData apiData,
           String accessToken,
           String defaultReference,
           Cache cache,
           Logger logger,
           Proxy proxy)

Constructor to build a proper Api object. This is not to build an Api object from an Api endpoint (the most usual case). In this case, you'll use the API.get method.

Parameters:

apiData - the data retrieved from the API document, ready to be stored in memory

accessToken - Your Oauth access token if you wish to use one (to access future content releases, for instance)

defaultReference - The default reference to use with queries. Will default to master if null

cache - instance of a class that implements the Cache interface, and will handle the cache

logger - instance of a class that implements the Logger interface, and will handle the logging

Api

@Deprecated
public Api(Api.ApiData apiData,
                       String accessToken,
                       Cache cache,
                       Logger logger,
                       Proxy proxy)

Deprecated.

Method Detail

getVersion

public static String getVersion()

Returns:

the kit version as declared in the pom.xml

get

public static Api get(String endpoint,
                      String accessToken,
                      String defaultReference,
                      Cache cache,
                      Logger logger,
                      Proxy proxy)

Entry point to get an Api object. Example: API api = API.get("https://lesbonneschoses.prismic.io/api", null, new Cache.BuiltInCache(999), new Logger.PrintlnLogger());

Parameters:

endpoint - the endpoint of your prismic.io content repository, typically https://yourrepoid.prismic.io/api

accessToken - Your Oauth access token if you wish to use one (to access future content releases, for instance)

defaultReference - The default reference to use with queries. Will default to master if null

cache - instance of a class that implements the Cache interface, and will handle the cache

logger - instance of a class that implements the Logger interface, and will handle the logging

proxy - an optional java.net.Proxy instance that defines the http proxy to be used

Returns:

the usable API object

get

public static Api get(String endpoint,
                      String accessToken,
                      String defaultReference,
                      Cache cache,
                      Logger logger)

Entry point to get an Api object. Example: API api = API.get("https://lesbonneschoses.prismic.io/api", null, new Cache.BuiltInCache(999), new Logger.PrintlnLogger());

Parameters:

endpoint - the endpoint of your prismic.io content repository, typically https://yourrepoid.prismic.io/api

accessToken - Your Oauth access token if you wish to use one (to access future content releases, for instance)

defaultReference - The default reference to use with queries. Will default to master if null

cache - instance of a class that implements the Cache interface, and will handle the cache

logger - instance of a class that implements the Logger interface, and will handle the logging

Returns:

the usable API object

get

public static Api get(String endpoint,
                      String accessToken,
                      Cache cache,
                      Logger logger)

get

public static Api get(String url,
                      Cache cache,
                      Logger logger)

get

public static Api get(String url,
                      String accessToken,
                      String defaultReference)

Entry point to get an Api object. Example: API api = API.get("https://lesbonneschoses.prismic.io/api", null);

Parameters:

url - the endpoint of your prismic.io content repository, typically https://yourrepoid.prismic.io/api

accessToken - Your Oauth access token if you wish to use one (to access future content releases, for instance)

Returns:

the usable API object

get

public static Api get(String url,
                      String accessToken)

Entry point to get an Api object. Example: API api = API.get("https://lesbonneschoses.prismic.io/api", null);

Parameters:

url - the endpoint of your prismic.io content repository, typically https://yourrepoid.prismic.io/api

accessToken - Your Oauth access token if you wish to use one (to access future content releases, for instance)

Returns:

the usable API object

get

public static Api get(String url)

Entry point to get an Api object. Example: API api = API.get("https://lesbonneschoses.prismic.io/api");

Parameters:

url - the endpoint of your prismic.io content repository, typically https://yourrepoid.prismic.io/api

Returns:

the usable API object

getLogger

public Logger getLogger()

getAccessToken

public String getAccessToken()

getCache

public Cache getCache()

getProxy

public Proxy getProxy()

getRefs

public List<Ref> getRefs()

From a properly built Api object, returns the ref IDs (points in a prismic.io repository's timeline, whether in the past, in the present, or in the future) to which the passed credentials give access.

Returns:

the list of ref IDs

getRef

public Ref getRef(String label)

From a properly built Api object, returns the ref with the corresponding label

Parameters:

label - the ref label as defined in the Writing Room

Returns:

the Ref, or null if not found

getBookmarks

public Map<String,String> getBookmarks()

From a properly built Api object, returns the map associating the bookmark names to their document IDs. Therefore, to get a bookmarked document's ID, it will look like this: api.getBookmarks().get("home")

Returns:

the map <name, id>

getTypes

public Map<String,String> getTypes()

From a properly built Api object, returns the map associating the type names to their readable text. Therefore, to get a type's readable text, it will look like this: api.getTypes().get("blog")

Returns:

the map <name, text>

getTags

public List<String> getTags()

From a properly built Api object, returns the list of available tags. Therefore, to get all available tags, it will look like this: api.getTags()

Returns:

the list of tags

getFormNames

public Map<String,String> getFormNames()

From a properly built Api object, returns the Map of available form names.

Returns:

the map <name, proper_name>

getForm

public Form.SearchForm getForm(String form)

From a properly built Api object, return a Form object that will allow to perform queries. Currently, all the forms offered by prismic.io are SearchForms, but this will change. To use it: api.get("everything").query(.....)......

Parameters:

form - the name of the form to query on

Returns:

the form to use to perform the query

See Also:

Form.SearchForm

getExperiments

public Experiments getExperiments()

Return the current experiments on the repository

Returns:

the Experiments object

getMaster

public Ref getMaster()

From a properly built Api object, returns the ref ID (points in a prismic.io repository's timeline, whether in the past, in the present, or in the future) of the master ref (the one presently live).

Returns:

the ref object representing the master ref

query

public Form.SearchForm query()

Start a query defaulting on the master reference (you can still override it)

query

public Form.SearchForm query(String q)

Start a query defaulting on the master reference (you can still override it)

query

public Form.SearchForm query(Predicate... predicates)

Start a query defaulting on the master reference (you can still override it)

getByIDs

public Form.SearchForm getByIDs(Iterable<String> ids,
                                String ref,
                                String lang)

Retrieve multiple documents from their ids on the given ref in the given language

getByIDs

public Form.SearchForm getByIDs(Iterable<String> ids,
                                String ref)

Retrieve multiple documents from their ids on the given ref

getByIDs

public Form.SearchForm getByIDs(Iterable<String> ids)

Retrieve multiple documents from their ids

queryFirst

public Document queryFirst(Predicate p,
                           String ref,
                           String lang)

Return the first document matching the predicate on the given ref in the given language

queryFirst

public Document queryFirst(Predicate p,
                           String ref)

Return the first document matching the predicate on the given reference

queryFirst

public Document queryFirst(Predicate p)

Return the first document matching the predicate on the master reference

getByID

public Document getByID(String documentId,
                        String ref,
                        String lang)

Retrieve a document by its ID on the given reference in the given language

Returns:

the document, or null if it doesn't exist

getByID

public Document getByID(String documentId,
                        String ref)

Retrieve a document by its ID on the given reference

Returns:

the document, or null if it doesn't exist

getByID

public Document getByID(String documentId)

Retrieve a document by its ID on the master reference

Returns:

the document, or null if it doesn't exist

getByUID

public Document getByUID(String documentType,
                         String documentUID,
                         String ref,
                         String lang)

Retrieve a document by its UID on the given reference in the given language

Returns:

the document, or null if it doesn't exist

getByUID

public Document getByUID(String documentType,
                         String documentUID,
                         String ref)

Retrieve a document by its UID on the given reference

Returns:

the document, or null if it doesn't exist

getByUID

public Document getByUID(String documentType,
                         String documentUID)

Retrieve a document by its UID on the master reference

Returns:

the document, or null if it doesn't exist

getBookmark

public Document getBookmark(String bookmark,
                            String ref)

getBookmark

public Document getBookmark(String bookmark)

previewSession

public String previewSession(String token,
                             LinkResolver linkResolver,
                             String defaultUrl,
                             Proxy proxy)

Return the URL to display a given preview

Parameters:

token - as received from Prismic server to identify the content to preview

linkResolver - the link resolver to build URL for your site

defaultUrl - the URL to default to return if the preview doesn't correspond to a document (usually the home page of your site)

Returns:

the URL you should redirect the user to preview the requested change

getOAuthInitiateEndpoint

public String getOAuthInitiateEndpoint()

getOAuthTokenEndpoint

public String getOAuthTokenEndpoint()