Skip to content

API Requirements

Jump to bottom
Za Wilgustus edited this page Dec 22, 2015 · 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 URL 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/)

Resource Collection - 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 objects that organize the resource collections. These things are generally just lists of references to the resource collections they contain. This 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  RC   Resource Obj    SC    Sub-Resrc Obj

Requirements

  1. BigIP objects SHOULD be represented by their configuration structure on the BigIP
  2. 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.
n = BigIP.ltm.nat_manager.create(name='mynat', partition='Common', ...)
  1. 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.
n = BigIP.ltm.nat(name='mynat', partition='Common')
  1. Objects that have sub-resource collections (i.e. Pools which have members) must include those collections as lists of proper sub-resource objects.
{'name': 'mypool', ..., 'members': [Member(), Member(), ...]}
  1. 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.
BigIP.ltm.create_nat()
# or
BigIP.ltm.nat_manager.create()
  1. 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)
BigIP.ltm.get_nats()
# or
BigIP.ltm.nat_manager.get_resources()
  1. Resource collections SHOULD be filterable according to the BigIP filter rules
BigIP.ltm.get_nats(filter='partition eq Common')
# or
BigIP.ltm.nat_manager.get_resources(filter='enabled eq true')
  1. READ, UPDATE, DELETE operations MUST only be available on resource objects. Calling an unsupported method MUST raise an appropriate exception.
# These should raise errors
BigIP.ltm.nat_manager.update()
BigIP.ltm.nat_manager.delete()

# This will work
my_nats = BigIP.ltm.nat_manager.get_resources()
for nat in my_nats:
    nat.read()
    if nat.enabled:
        nat.disabled = True
        nat.update()
    else:
        nat.delete()
  1. 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.
  2. The __repr__ attribute for the resource objects SHOULD be defined such that the consumer can use it for debugging.
  3. 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 and name.
  4. Create methods for resource objects SHOULD validate that all required arguments are present prior to sending them to the BigIP in the request.
  5. 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.
  6. 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.
  7. 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