module Prismic

Return an API instance @api

The access token and HTTP client can be provided.

The HTTP Client must responds to same method than {DefaultHTTPClient}.

@overload api(url)

Simpler syntax (no configuration)
@param [String] url The URL of the prismic.io repository

@overload api(url, opts)

Standard use
@param [String] url The URL of the prismic.io repository
@param [Hash] opts The options
@option opts [String] :access_token (nil) The access_token
@option opts :http_client (DefaultHTTPClient) The HTTP client to use
@option opts :api_cache (nil) The caching object for the /api endpoint cache (for instance Prismic::Cache) to use
@option opts :cache (nil) The caching object (for instance Prismic::Cache) to use, or false for no caching

@overload api(url, access_token)

Provide the access_token (only)
@param [String] url The URL of the prismic.io repository
@param [String] access_token The access token

@raise PrismicWSConnectionError

@return [API] The API instance related to this repository

# File lib/prismic.rb, line 65
def self.api(url, opts=nil)
  if (not url =~ /\A#{URI::regexp(['http', 'https'])}\z/)
    raise ArgumentError.new("Valid web URI expected")
  end
  opts ||= {}
  opts = {access_token: opts} if opts.is_a?(String)
  API.start(url, opts)
end

Build a {LinkResolver} instance @api

The {LinkResolver} will help to build URL specific to an application, based on a generic prismic.io's {Fragments::DocumentLink Document link}.

@param ref [Ref] The ref to use @yieldparam doc_link [Fragments::DocumentLink] A DocumentLink instance @yieldreturn [String] The application specific URL of the given document

@return [LinkResolver] the {LinkResolver} instance

# File lib/prismic.rb, line 677
def self.link_resolver(ref, &blk)
  LinkResolver.new(ref, &blk)
end

Check a token and return an access_token

This method allows to check the token received when the user has been redirected from the OAuth2 server. It returns an access_token that can be used to authenticate the user on the API.

@param url [String] The URL of the prismic.io repository @param oauth_opts [Hash] The OAuth2 options @param api_opts [Hash] The API options (the same than accepted by the

{api} method)

@option oauth_opts :client_id [String] The Application's client ID @option oauth_opts :redirect_uri [String] The Application's secret

@raise PrismicWSConnectionError

@return [String] the access_token

# File lib/prismic.rb, line 116
def self.oauth_check_token(url, oauth_opts, api_opts=nil)
  api_opts ||= {}
  api_opts = {access_token: api_opts} if api_opts.is_a?(String)
  API.oauth_check_token(url, oauth_opts, api_opts)
end

Build the URL where the user can be redirected to authenticated himself using OAuth2. @api

@note: The endpoint depends on the repository, so an API call is made to fetch it.

@param url The URL of the prismic.io repository @param oauth_opts [Hash] The OAuth2 options @param api_opts [Hash] The API options (the same than accepted by the {api}

method)

@option oauth_opts :client_id [String] The Application's client ID @option oauth_opts :redirect_uri [String] The Application's secret @option oauth_opts :scope [String] The desired scope

@raise PrismicWSConnectionError

@return [String] The built URL

# File lib/prismic.rb, line 93
def self.oauth_initiate_url(url, oauth_opts, api_opts=nil)
  api_opts ||= {}
  api_opts = {access_token: api_opts} if api_opts.is_a?(String)
  API.oauth_initiate_url(url, oauth_opts, api_opts)
end