Object interface

Object interface is accessible via so called entry point. Check here to understand how entry points are obtained.

NOTE: Whenever user performs an operation and the operation fails one of built-in exceptions is raised.

class resource_api.service.EntryPoint(service, user)

Represents user specific means of access to object interface.

get_resource(resource_class)

resource_class (Resource subclass)

>>> entry_point.get_resource(Student)
<RootResourceCollection object>

get_resource_by_name(resource_name)

resource_name (string)

namespace + ”.” + resource_name, where namespace can be a custom namespace or resource’s module name

>>> entry_point.get_resource_by_name("school.Student")
<RootResourceCollection object>
>>> entry_point.get_resource_by_name("com.example.module.education.Student")
<RootResourceCollection object>

user

User object returned by Service._get_user method

Root resource collection

class resource_api.resource.RootResourceCollection(entry_point, resource_interface, params=None)

Root resource collection is actually a normal resource collection with two extra methods: create and get.

create(data, link_data=None)

>>> student_collection = entry_point.get_resource(Student)
>>> new_student = student_collection.create({"first_name": "John",
>>>                                          "last_name": "Smith",
>>>                                          "email": "foo@bar.com",
>>>                                          "birthday": "1987-02-21T22:22:22"},
>>>                                         {"courses": [{"@target": "Maths", "grade": 4},
>>>                                                      {"@target": "Sports"}]})

get(pk)

>>> student_collection = entry_point.get_resource(Student)
>>> existing_student = student_collection.get("john@example.com")

Resource collection

class resource_api.resource.ResourceCollection(entry_point, resource_interface, params=None)

The entity that represents a pile of resources.

>>> student_collection = entry_point.get_resource(Student)

The collection is iterable:

>>> for student in student_collection:
>>>    ...

If Resource.get_uris is implemented to return an indexable entity the collection elements can be accessed by index as well:

>>> student = student_collection[15]

count()

Returns count of all items within the system that satisfy filtering criterias.

NOTE: len(collection) is supposed to return the same result as collection.count(). The key difference between them is that len needs to fetch all items in the collection meanwhile collection.count() relies on Resource.get_count

>>> len(student_collection)
4569
>>> student_collection.count()
4569

filter(params=None)

Filtering options can be applied to collections to return new collections that contain a subset of original items:

NOTE: filtering operations applied to root collections return normal collections

>>> student_collection = entry_point.get_resource(Student)
>>> new_collection = student_collection.filter(params={"name__startswith": "Abr"})

Resource item

class resource_api.resource.ResourceInstance(entry_point, resource_interface, pk)

Whenever creating new or fetching existing resources resource instances are returned. Resource instances are also returned whenever iterating over resource collections.

data

Returns data associated with the resource

>>> student.data
{"first_name": "John", "last_name": "Smith", "email": "foo@bar.com", "birthday": "1987-02-21T22:22:22"}

delete()

Removes the resource

>>> student.delete()
>>> student.data
...
DoesNotExist: ...

links

Returns a link holder

pk

Returns PK of the resource

>>> student.pk
"foo@bar.com"

update(data)

Changes specified fields of the resource

>>> student.update({"first_name": "Looper"})
>>> student.data
{"first_name": "Looper", "last_name": "Smith", "email": "foo@bar.com", "birthday": "1987-02-21T22:22:22"}

Link holder

class resource_api.link.LinkHolder(entry_point, resource_instance, pk)

Accessor for all the links associated with the resource

For link with cardinality “MANY” RootLinkCollection is returned:

>>> student.links.courses
<RootLinkCollection object>

For link with cardinality “ONE” LinkToOne is returned:

>>> course.links.teacher
<LinkToOne object>

Root link collection

class resource_api.link.RootLinkCollection(target_collection, forward_link_instance, backward_link_instance, source_pk, params=None)

Root link collection is actually a normal link collection with two extra methods: create and get.

create(data)

data (dict)

has to have at least one key called @target - its value must be a PK of target resource instance

>>> student_courses = student.links.courses
>>> new_link_to_course = student_courses.create({"@target": "Maths"})

get(target_pk)

target_pk

PK of target resource instance

>>> student_courses = student.links.courses
>>> exisiting_link_to_course = student_courses.get("Biology")

Link collection

class resource_api.link.LinkCollection(target_collection, forward_link_instance, backward_link_instance, source_pk, params=None)

The entity that represents a pile of resource links.

>>> student_courses = student.links.courses

The collection is iterable:

>>> for link in student_courses:
>>>    ...

If Link.get_uris is implemented to return an indexable entity the collection elements can be accessed by index as well:

>>> link = student_courses[15]

count()

Returns count of all items within the system that satisfy filtering criterias.

NOTE: len(collection) is supposed to return the same result as collection.count(). The key difference between them is that len needs to fetch all items in the collection meanwhile collection.count() relies on Link.get_count

>>> len(student_courses)
4569
>>> student_courses.count()
4569

filter(params=None)

Filtering options can be applied to collections to return new collections that contain a subset of original items:

NOTE: filtering operations applied to root collections return normal collections

>>> student_courses = student.links.courses
>>> new_link_collection = student_courses.filter(grade__gte=3)

Link instance

class resource_api.link.LinkInstance(target_collection, forward_link_instance, backward_link_instance, source_pk, target_pk)

Whenever creating new or fetching existing links link instances are returned. Link instances are also returned whenever iterating over link collections.

data

Returns data associated with the link

>>> link.data
{"grade": 3}

delete()

Removes the link

>>> link.delete()
>>> link.data
...
DoesNotExist: ...

target

Returns a ResourceInstance associated with target resource.

>>> link.target.pk
"Maths"

update(data)

Changes specified fields of the link

>>> link.update({"grade": 4})
>>> link.data
{"grade": 4}

NOTE: CANNOT be used to change @target

Link to one

class resource_api.link.LinkToOne(target_collection, forward_link_instance, backward_link_instance, source_pk)

Represents a relationship with cardinality ONE

item

Returns LinkInstance if it exists, raises DoesNotExist error otherwise

>>> course.links.teacher.item.delete()
>>> course.links.teacher.item
...
DoesNotExist ...

set(data)

Does the same thing as update method but CAN change the @target

>>> course.links.teacher.item.target.pk
"Hades"
>>> course.links.teacher.set({"@target": "Zeuz"})
>>> course.links.teacher.item.target.pk
"Zeus"