class Prismic::API
The API
is the main class
Attributes
@return [String]
@return [Hash{String => String}] list of bookmarks, as name -> documentId
@return [Experiments] list of all experiments from Prismic
@return [Hash{String => Form}] list of forms, as name -> Form
Returns the master {Ref reference} @api
@return [Ref] The master {Ref reference}
Returns the master {Ref reference} @api
@return [Ref] The master {Ref reference}
@return [Hash{String => Ref}] list of references, as label -> reference
Public Class Methods
Fetch the API
information from the Prismic.io server
# File lib/prismic/api.rb, line 186 def self.get(url, access_token=nil, http_client=Prismic::DefaultHTTPClient, api_cache=Prismic::DefaultCache) data = {} data['access_token'] = access_token if access_token cache_key = url + (access_token ? ('#' + access_token) : '') api_cache.get_or_set(cache_key, nil, 5) { res = http_client.get(url, data, 'Accept' => 'application/json') case res.code when '200' res.body when '401', '403' begin json = JSON.load(res.body) raise PrismicWSAuthError.new( json['error'], json['oauth_initiate'], json['oauth_token'], http_client ) rescue => e raise PrismicWSConnectionError.new(res, e) end else raise PrismicWSConnectionError, res end } end
# File lib/prismic/api.rb, line 37 def initialize(json, access_token, http_client, cache) @json = json @access_token = access_token @http_client = http_client yield self if block_given? @cache = cache self.master = refs.values && refs.values.map { |ref| ref if ref.master? }.compact.first raise BadPrismicResponseError, 'No master Ref found' unless master end
# File lib/prismic/api.rb, line 264 def self.oauth_check_token(url, oauth_params, api_opts={}) oauth = begin api = self.start(url, api_opts) api.oauth rescue PrismicWSAuthError => e e.oauth end oauth.check_token(oauth_params) end
# File lib/prismic/api.rb, line 244 def self.oauth_initiate_url(url, oauth_opts, api_opts={}) oauth = begin api = self.start(url, api_opts) api.oauth rescue PrismicWSAuthError => e e.oauth end oauth.initiate_url(oauth_opts) end
# File lib/prismic/api.rb, line 225 def self.parse_api_response(data, access_token, http_client, cache) data_forms = data['forms'] || [] data_refs = data.fetch('refs'){ raise BadPrismicResponseError, "No refs given" } new(data, access_token, http_client, cache) {|api| api.bookmarks = data['bookmarks'] api.forms = Hash[data_forms.map { |k, form| [k, Form.from_json(api, form)] }] api.refs = Hash[data_refs.map { |ref| scheduled_at = ref['scheduledAt'] [ref['label'].downcase, Ref.new(ref['id'], ref['ref'], ref['label'], ref['isMasterRef'], scheduled_at && Time.at(scheduled_at / 1000.0))] }] api.tags = data['tags'] api.types = data['types'] api.oauth = OAuth.new(data['oauth_initiate'], data['oauth_token'], http_client) api.experiments = Experiments.parse(data['experiments']) } end
# File lib/prismic/api.rb, line 213 def self.start(url, opts={}) http_client = opts[:http_client] || Prismic::DefaultHTTPClient access_token = opts[:access_token] # We don't use ||= because we want to keep the DefaultCache if nil was explicitly passed api_cache = opts.has_key?(:api_cache) ? opts[:api_cache] : Prismic::DefaultCache cache = opts.has_key?(:cache) ? opts[:cache] : Prismic::DefaultCache resp = get(url, access_token, http_client, api_cache) json = JSON.load(resp) parse_api_response(json, access_token, http_client, cache) end
Public Instance Methods
Retrieve all documents (paginated) @param opts [Hash] query options (page, pageSize, ref, etc.)
# File lib/prismic/api.rb, line 96 def all(opts={}) ref = opts['ref'] || opts[:ref] || self.master.ref form('everything', opts).submit(ref) end
# File lib/prismic/api.rb, line 181 def as_json @json end
Get a bookmark by its name @api @param [String] The bookmark's name
@return [String] The bookmark document id
# File lib/prismic/api.rb, line 52 def bookmark(name) bookmarks[name] end
@deprecated Use {#form} instead.
# File lib/prismic/api.rb, line 78 def create_search_form(name, data={}, ref={}) unless @@warned_create_search_form warn '[DEPRECATION] `create_search_form` is deprecated. Please use `form` instead.' @@warned_create_search_form = true end form(name, data, ref) end
Returns a {Prismic::SearchForm search form} by its name. This is where you start to query a repository. @api @param name [String] The name of the form @param data [Hash] Default values @param ref [type] Default {Ref reference}
@return [SearchForm] The search form
# File lib/prismic/api.rb, line 72 def form(name, data={}, ref={}) form = self.forms[name] form and form.create_search_form(data, ref) end
Retrieve one document by its id @param id [String] the id to search @param opts [Hash] query options (page, pageSize, ref, etc.) @return the document, or nil if not found
# File lib/prismic/api.rb, line 105 def get_by_id(id, opts={}) unless opts.key?("lang") opts["lang"] = '*' end query(Prismic::Predicates::at('document.id', id), opts)[0] end
Retrieve multiple documents by their ids @param ids [String] the ids to fetch @param opts [Hash] query options (page, pageSize, ref, etc.) @return the document, or nil if not found
# File lib/prismic/api.rb, line 130 def get_by_ids(ids, opts={}) unless opts.key?("lang") opts["lang"] = '*' end query(Prismic::Predicates::in('document.id', ids), opts) end
Retrieve one document by its uid @param typ [String] the document type's name @param uid [String] the uid to search @param opts [Hash] query options (ref, etc.) @return the document, or nil if not found
# File lib/prismic/api.rb, line 118 def get_by_uid(typ, uid, opts={}) unless opts.key?("lang") opts["lang"] = '*' end query(Prismic::Predicates::at('my.'+typ+'.uid', uid), opts)[0] end
Retrieve multiple documents by their uids @param typ [String] the document type's name @param uids [String] the uids to search @param opts [Hash] query options (ref, etc.)
# File lib/prismic/api.rb, line 143 def get_by_uids(typ, uids, opts = {}) unless opts.key?("lang") opts["lang"] = '*' end query(Prismic::Predicates::in('my.'+typ+'.uid', uids), opts) end
Retrieve one single typed document by its type @param typ [String] the document type's name @param opts [Hash] query options (ref, etc.) @return the document, or nil if not found
# File lib/prismic/api.rb, line 155 def get_single(typ, opts={}) query(Prismic::Predicates::at('document.type', typ), opts)[0] end
Is the cache enabled on this API
object?
@return [Boolean]
# File lib/prismic/api.rb, line 26 def has_cache? !!cache end
# File lib/prismic/api.rb, line 275 def oauth_check_token(params) unless @@warned_oauth_check_token warn "[DEPRECATION] Method `API#oauth_check_token` is deprecated. " + "Please use `Prismic::API.oauth_check_token` instead." @@warned_oauth_check_token = true end oauth.check_token(params) end
# File lib/prismic/api.rb, line 255 def oauth_initiate_url(opts) if !@@warned_oauth_initiate_url warn "[DEPRECATION] Method `API#oauth_initiate_url` is deprecated. " + "Please use `Prismic::API.oauth_initiate_url` instead." @@warned_oauth_initiate_url = true end oauth.initiate_url(opts) end
Return the URL to display a given preview @param token [String] as received from Prismic
server to identify the content to preview @param link_resolver the link resolver to build URL for your site @param default_url [String] the URL to default to return if the preview doesn't correspond to a document (usually the home page of your site)
@return [String] the URL to redirect the user to
# File lib/prismic/api.rb, line 167 def preview_session(token, link_resolver, default_url) response = self.http_client.get(token, {}, 'Accept' => 'application/json') if response.code.to_s != '200' return default_url end json = JSON.load(response.body) documents = self.form('everything').query(Prismic::Predicates.at('document.id', json['mainDocument'])).lang("*").submit(token) if documents.results.size > 0 link_resolver.link_to(documents.results[0]) else default_url end end
Perform a query on this API
. Use the master reference is no ref is specified in data. @param q [String] the query to perform @param opts [Hash] query options (page, pageSize, ref, etc.)
# File lib/prismic/api.rb, line 89 def query(q, opts={}) ref = opts['ref'] || opts[:ref] || self.master.ref form('everything', opts).query(q).submit(ref) end
Get a {Ref reference} by its alias @api @param name [String] The reference's alias
@return [Ref] The reference
# File lib/prismic/api.rb, line 61 def ref(name) refs[name.downcase] end