URLs¶
Proper URL patterns are the backbone of a ResourceModel. URLs are defined in a ResourceModel as a tuple of nap_urls
–a thin wrapper around a python-formatted string. These are defined and tied to a ResourceModel through the urls, prepend_urls, and append_urls. These are stored in the ResourceModel’s _meta
By default, ResourceModels have two nap_urls that allow them to make all common calls to a to-spec REST API:
(
nap_url('%(resource_name)s/', create=True, lookup=False, collection=True),
nap_url('%(resource_name)s/%(resource_id)s/', update=True),
)
How a URL lookup works¶
nap_urls contain three parts of information:
- The kinds of lookups that this url can be used for.
- The URL String itself
- The names of variables needed to generate
On calls that are backed by a URL, Nap will iterate through every URL in it’s url list looking for a match. A match is considered a URL where
- The URL is valid for the type of request being attempted
- The variablres required to generated a valid URL are available.
Let’s dive into each part of a URL to understand this process a bit better.
Lookup Types¶
Lookup types closely match the kind of operations possible with an API. They are
create
, lookup
, update
, collection
.
- create: URLs that can be used to create new resources. Used for the
create()
method. - lookup: URLs that can be used to retreive a single resource. Used for the
get()
method when using keyword arguments. - update: URLs that can be used to create update an existing resource. Used for the
update()
method. - collection: URLs that can be used to retrieve collections of resources. Used for the
filter()
andall()
methods.
Valid URL Strings¶
A URL string is simply a python string, optionally containing dictionary-format variables.
nap bases it’s required variables partially on any format variables contained in the URL string.
URL Variables¶
LookupURLs may require variables to fully resolve. Required variables are either
- Python string format variables contained in the url_string, or
- Any variables named passed into a
__init__
‘sparam
parameter. These variables are passed into the URL via a URL query string.
ResourceModel
passes in three kinds of variables into the LookupURL’s match function to determine if all required variables are available for URL resolution:
- Keyword arguments passed to lookup function (eg,
ResourceModel.get()
,ResourceModel.update()
) - The values of fields, where the name of the field is passed as the variable name.
- Meta variables specific to the subclass of ResourceModel
The above lists these groups in order of presidence–eg, If update()
is called on a ResourceModel with a resource_name of ‘person’, but a keyword argument of resource_name='author'
, %(resource_name)s will resolve to author
.
Meta Variables available for URLs¶
Currently, there is only one meta variable passed to LookupURL.
resource_name
¶
The resource name of the ResourceModel. Equal to resource_name
URL API¶
-
class
nap.lookup.
LookupURL
¶ Class in charge of resolving variable URLs based on keyword arguments. Used for any dynamic API method on
ResourceModel
-
LookupURL.
__init__
(url_string[, params=None, create=False, update=False, lookup=False, collection=False])¶ Parameters: - url_string – python-formatted string representing a URL
- params – an iterable of variables names required by the URL, as passed in a GET query string.
- create – Designates whether or not the URL is valid for create operations
- update – Designates whether or not the URL is valid for create operations
- lookup – Designates whether or not the URL is valid for create operations
- collection – Designates whether or not the URL is valid for create operations
-
LookupURL.
url_vars
¶ Returns a tuple the names of variables contained within a
LookupURL
-
LookupURL.
required_vars
¶ Returns a tuple of the the names of all variables required to successfully resolve a URL.
-
LookupURL.
match
(**lookup_vars)¶ Attempts to resolve a string of a URL, resolving any variables based on
lookup_vars
.Returns a two tuple of the matching URL string and extra lookup variables that were passed in but not part of the required values.
If no match is found, a two tuple of (
None
,None
) is returned.Parameters: lookup_vars – A dict-like variable mapping URL variables names to