Class: Prismic::API

Inherits:
Object
  • Object
show all
Defined in:
lib/prismic/api.rb

Overview

The API is the main class

Defined Under Namespace

Classes: BadPrismicResponseError, OAuth, PrismicWSAuthError, PrismicWSConnectionError

Constant Summary collapse

@@warned_create_search_form = 
false
@@warned_oauth_initiate_url = 
false
@@warned_oauth_check_token = 
false

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(json, access_token, http_client, cache) {|_self| ... } ⇒ API

Returns a new instance of API.

Yields:

  • (_self)

Yield Parameters:

  • _self (Prismic::API) —

    the object that the method was called on

Raises:



37
38
39
40
41
42
43
44
45
 
# 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

Instance Attribute Details

#access_token ⇒ String (readonly)

Returns:

  • (String) 


11
12
13
 
# File 'lib/prismic/api.rb', line 11

def access_token
  @access_token
end

#bookmarks ⇒ Hash{String => String}

Returns list of bookmarks, as name -> documentId.

Returns:

  • (Hash{String => String}) —

    list of bookmarks, as name -> documentId



16
17
18
 
# File 'lib/prismic/api.rb', line 16

def bookmarks
  @bookmarks
end

#cache ⇒ Object

Returns the value of attribute cache.



19
20
21
 
# File 'lib/prismic/api.rb', line 19

def cache
  @cache
end

#experiments ⇒ Experiments

Returns list of all experiments from Prismic.

Returns:

  • (Experiments) —

    list of all experiments from Prismic



21
22
23
 
# File 'lib/prismic/api.rb', line 21

def experiments
  @experiments
end

#forms ⇒ Hash{String => Form}

Returns list of forms, as name -> Form.

Returns:

  • (Hash{String => Form}) —

    list of forms, as name -> Form



18
19
20
 
# File 'lib/prismic/api.rb', line 18

def forms
  @forms
end

#http_client ⇒ Object (readonly)

Returns the value of attribute http_client.



12
13
14
 
# File 'lib/prismic/api.rb', line 12

def http_client
  @http_client
end

#json ⇒ Object (readonly)

Returns the value of attribute json.



9
10
11
 
# File 'lib/prismic/api.rb', line 9

def json
  @json
end

#master ⇒ Ref Also known as: master_ref

Returns the master reference

Returns:



34
35
36
 
# File 'lib/prismic/api.rb', line 34

def master
  @master
end

#oauth ⇒ Object

Returns the value of attribute oauth.



19
20
21
 
# File 'lib/prismic/api.rb', line 19

def oauth
  @oauth
end

#refs ⇒ Hash{String => Ref}

Returns list of references, as label -> reference.

Returns:

  • (Hash{String => Ref}) —

    list of references, as label -> reference



14
15
16
 
# File 'lib/prismic/api.rb', line 14

def refs
  @refs
end

#tags ⇒ Object

Returns the value of attribute tags.



19
20
21
 
# File 'lib/prismic/api.rb', line 19

def tags
  @tags
end

#types ⇒ Object

Returns the value of attribute types.



19
20
21
 
# File 'lib/prismic/api.rb', line 19

def types
  @types
end

Class Method Details

.get(url, access_token = nil, http_client = Prismic::DefaultHTTPClient, api_cache = Prismic::DefaultCache) ⇒ Object

Fetch the API information from the Prismic.io server



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# 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

.oauth_check_token(url, oauth_params, api_opts = {}) ⇒ Object 



264
265
266
267
268
269
270
271
272
273
 
# 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

.oauth_initiate_url(url, oauth_opts, api_opts = {}) ⇒ Object 



244
245
246
247
248
249
250
251
252
253
 
# 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

.parse_api_response(data, access_token, http_client, cache) ⇒ Object 



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# 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['id']), 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

.start(url, opts = {}) ⇒ Object 



213
214
215
216
217
218
219
220
221
222
223
 
# 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

Instance Method Details

#all(opts = {}) ⇒ Object

Retrieve all documents (paginated)

Parameters:

  • opts (Hash) (defaults to: {}) —

    query options (page, pageSize, ref, etc.)



96
97
98
99
 
# File 'lib/prismic/api.rb', line 96

def all(opts={})
  ref = opts['ref'] || opts[:ref] || self.master.ref
  form('everything', opts).submit(ref)
end

#as_json ⇒ Object 



181
182
183
 
# File 'lib/prismic/api.rb', line 181

def as_json
  @json
end

#bookmark(name) ⇒ String

Get a bookmark by its name

Parameters:

  • The (String) —

    bookmark's name

Returns:

  • (String) —

    The bookmark document id



52
53
54
 
# File 'lib/prismic/api.rb', line 52

def bookmark(name)
  bookmarks[name]
end

#create_search_form(name, data = {}, ref = {}) ⇒ Object

Deprecated.

Use #form instead.



78
79
80
81
82
83
84
 
# 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

#form(name, data = {}, ref = {}) ⇒ SearchForm

Returns a search form by its name. This is where you start to query a repository.

Parameters:

  • name (String) —

    The name of the form

  • data (Hash) (defaults to: {}) —

    Default values

  • ref (type) (defaults to: {}) —

    Default reference

Returns:



72
73
74
75
 
# 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

#get_by_id(id, opts = {}) ⇒ Object Also known as: getByID

Retrieve one document by its id

Parameters:

  • id (String) —

    the id to search

  • opts (Hash) (defaults to: {}) —

    query options (page, pageSize, ref, etc.)

Returns:

  • the document, or nil if not found



105
106
107
108
109
110
 
# 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

#get_by_ids(ids, opts = {}) ⇒ Object Also known as: getByIDs

Retrieve multiple documents by their ids

Parameters:

  • ids (String) —

    the ids to fetch

  • opts (Hash) (defaults to: {}) —

    query options (page, pageSize, ref, etc.)

Returns:

  • the document, or nil if not found



130
131
132
133
134
135
 
# 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

#get_by_uid(typ, uid, opts = {}) ⇒ Object Also known as: getByUID

Retrieve one document by its uid

Parameters:

  • typ (String) —

    the document type's name

  • uid (String) —

    the uid to search

  • opts (Hash) (defaults to: {}) —

    query options (ref, etc.)

Returns:

  • the document, or nil if not found



118
119
120
121
122
123
 
# 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

#get_by_uids(typ, uids, opts = {}) ⇒ Object Also known as: getByUIDs

Retrieve multiple documents by their uids

Parameters:

  • typ (String) —

    the document type's name

  • uids (String) —

    the uids to search

  • opts (Hash) (defaults to: {}) —

    query options (ref, etc.)



143
144
145
146
147
148
 
# 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

#get_single(typ, opts = {}) ⇒ Object Also known as: getSingle

Retrieve one single typed document by its type

Parameters:

  • typ (String) —

    the document type's name

  • opts (Hash) (defaults to: {}) —

    query options (ref, etc.)

Returns:

  • the document, or nil if not found



155
156
157
 
# File 'lib/prismic/api.rb', line 155

def get_single(typ, opts={})
  query(Prismic::Predicates::at('document.type', typ), opts)[0]
end

#has_cache? ⇒ Boolean

Is the cache enabled on this API object?

Returns:

  • (Boolean) 


26
27
28
 
# File 'lib/prismic/api.rb', line 26

def has_cache?
  !!cache
end

#oauth_check_token(params) ⇒ Object 



275
276
277
278
279
280
281
282
 
# 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

#oauth_initiate_url(opts) ⇒ Object 



255
256
257
258
259
260
261
262
 
# 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

#preview_session(token, link_resolver, default_url) ⇒ String

Return the URL to display a given preview (usually the home page of your site)

Parameters:

  • token (String) —

    as received from Prismic server to identify the content to preview

  • link_resolver —

    the link resolver to build URL for your site

  • default_url (String) —

    the URL to default to return if the preview doesn't correspond to a document

Returns:

  • (String) —

    the URL to redirect the user to



167
168
169
170
171
172
173
174
175
176
177
178
179
 
# 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

#query(q, opts = {}) ⇒ Object

Perform a query on this API. Use the master reference is no ref is specified in data.

Parameters:

  • q (String) —

    the query to perform

  • opts (Hash) (defaults to: {}) —

    query options (page, pageSize, ref, etc.)



89
90
91
92
 
# 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

#ref(name) ⇒ Ref

Get a reference by its alias

Parameters:

  • name (String) —

    The reference's alias

Returns:

  • (Ref) —

    The reference



61
62
63
 
# File 'lib/prismic/api.rb', line 61

def ref(name)
  refs[name.downcase]
end