Skip to content

API Requirements

Jump to bottom
Za Wilgustus edited this page Jan 12, 2016 · 13 revisions

Definitions

Resource Object - Terminal object in the API. For example a single nat instance. These are things that have a type and do not have 'collection' in their kind attribute (i.e. "kind":"natstate"). They usually have a URI that ends in /~<partition>~<name>/.

Sub-Collection - Some more complicated objects have sub-resources, but are accessed through the main resource object (i.e. pool/~Common~mypool/members/)

Sub-Resource Object - These are the actual objects that are part of the sub-collection and accessed via the main resource object (i.e. pool/~Common~mypool/members/~Common~m1:80/)

Collection Resource - This is a list of resource objects. For example all nat instances configured on the system. These are things that do have 'collection' in their kind attribute (i.e. "kind":"natcollectionstate"). The have a URL that ends in the name of the objects you are getting a list of (i.e. ltm/nat/).

Organizing Collection - This is the high level object that organizes the collection resources. These things are generally just dictionaries of references to the collection resources they contain. These are things like ltm, sys, cm etc.

Example using the URL that points to the member sub-resource object of the pool resource object that is contained in the ltm organizing collection

http://192.168.1.1/mgmt/tm/ltm/pool/~Common~mypool/members/~Common~m1:80/
                  |-------|---|----|--------------|-------|-------------|
                     OC     OC  CR   Resource Obj    SC    Sub-Resrc Obj

Requirements

  1. BigIP objects SHOULD be represented by their configuration structure on the BigIP
  2. After working with this an considering the consumer we felt it was better more closely mirror the organization structure of the various objects.
from f5.bigip import BigIP
bigip = BigIP('192.168.1.1', 'admin', 'admin')

# Returns an OrganizingCollection (dict) that contains the resource collections keyed on their names.
ltm_collections = bigip.ltm

# Returns a ResourceCollection (list) that contains Pool objects.  This does GET to BigIP and returns a list
pools = bigip.ltm.pool_collection
for pool in pools[1:3]:
    print pool.name

# Instantiate an empty Pool object, and then explicitly create it
new_pool = bigip.ltm.pool_collection.pool
new_pool.create(name='new_pool',
                partition='partition',
                attr1='foo',
                attr2='bar')

# Get an existing pool, this will return an error if the pool doesn't exist on the BIGIP
try:
    existing_pool = bigip.ltm.pool_collection.pool(
        name='existing_pool', partition='mypartition')
except pool.ResourceNotFound:
    new_pool = bigip.ltm.pool_collection.pool.create(
        name='new_pool', partition='partition', attr1='foo', attr2='bar')
    print new_pool.name

# Update a pool
new_pool.description = "New Description"
new_pool.update()
# or
new_pool.update(description="New Description")

# Refresh a pool - This will 'refresh' the object with the current state on the BIGIP
new_pool.refresh()

# Delete a pool
new_pool.delete()

# Get the members of a pool, this returns a Sub-Resource Collection
members = new_pool.member_collection
for member in members[::-1]:
    print member.name

# Get a single member of a pool
member_0 = new_pool.member_collection[0]

# Get a list of members with some criteria
member_list = new_pool.member_collection.filter(enabled=True, partition='mypartion')

# Create a new member
new_member = new_pool.member_collection.member(name='m1:80', 
    partition='mypartition',arg1='foo', arg2='bar', ...)
  1. Users MUST be able to create new resource objects on the BigIP including their sub-resource objects
    1. Creation of new resource objects must return the object that can be operated on with supported CRUD methods.
  2. Users MUST be able to access existing resource objects on the system by specifying the partition and name of the object
    1. Accessing existing objects MUST return the object that can be operated on with supported CRUD methods.
  3. Objects that have sub-resource collections (i.e. Pools which have members) must include those collections as lists of proper sub-resource objects.
  4. Create methods for resource objects MUST only be accessed via their resource collection (or a manager attached to it). Calling an unsupported method MUST raise an appropriate exception.
  5. Consumers of the API MUST be able to list all of the resource collection's child objects via the resource collection object (or a manager attached to it)
  6. Resource collections SHOULD be filterable according to the BigIP filter rules
  7. READ, UPDATE, DELETE operations MUST only be available on resource objects. Calling an unsupported method MUST raise an appropriate exception.
  8. The __str__ attribute for the resource objects SHOULD be defined such that the the consumer can uniquely identify the object. Something like ltm/nat/~Common~mynat or Common/mynat would be good.
  9. The __repr__ attribute for the resource objects SHOULD be defined such that the consumer can use it for debugging.
  10. The __eq__ for resource objects SHOULD be defined such that the consumer can easily compare objects to see if they have the same value. The equivalence check may be as simple as having the same partition, name and generation values.
  11. Create methods for resource objects SHOULD validate that all required arguments are present prior to sending them to the BigIP in the request.
  12. Update methods for objects SHOULD validate that all read-only attributes that cause an error on the system if present are validated/errored prior to sending the update request to the BigIP.
  13. Delete methods for objects SHOULD delete the object on the BigIP and delete its self in such a way that the object is no longer valid for users to operate on.
  14. HTTP Errors raised by the request to the BigIP MUST be raised by the API back to the caller. For example if the use of the API causes a 404 then this should raise an error that the caller can catch.
Clone this wiki locally