The source for the first release of the SP REST API Cookbook

Author: arbor-acaird

README.md

@@ -1,2 +1,30 @@
-# sp-rest-api-cookbook
-A document with examples of using the Arbor SP REST API, intended as a supplement to the online REST API documentation
+# Using the Arbor Networks SP REST API: SP v8.3 API v2
+
+This repository contains the source material for a document that is
+intended to be a gentle, user-facing introduction to the Arbor 
+Networks SP REST API.
+
+## Formatting
+
+The file `sp-rest-api-tutorial.txt` is formatted according to
+[Emacs Orgmode](http://orgmode.org/guide/) formatting rules.  You
+don't need Emacs or Orgmode to edit this file; the examples in the
+file should be sufficient guidance for adding to it and the link to
+the [Orgmode Guide](http://orgmode.org/guide/) may also help.
+
+## Contributing
+
+All contributions are greatly appreciated; pull requests, emailed
+patches, emailed edits, printed and written-on paper, whatever works
+easiest for you.
+
+## Rendering
+
+If you want to render this you can use Emacs+Orgmode's Export (`C-e`)
+command to produce HTML, PDF, etc.
+
+## Releases
+
+Rendered versions will be released periodically at this Github site;
+unless you are intending to contribute or want to render your own
+version, the rendered releases are probably the best option for you.

code-examples/BI-to-MO.py

@@ -0,0 +1,197 @@
+from __future__ import print_function
+import csv
+import json
+import requests  # version: 2.18.4
+import sys
+
+CERTFILE="../certfile"
+
+def api_request(URL, key, body=None):
+    """ Creates and makes a post request to an SP
+    api service
+
+    Args:
+        URL: A URL including an SP leader and
+             SP resource
+        key: An api key generated on the given
+             SP leader
+        body: JSON formatted string to be supplied
+              as the request's body
+
+    Returns:
+        'data' value of an SP api response
+    """
+
+    headers = {
+        'X-Arbux-APIToken': key,
+        'Content-Type': 'application/vnd.api+json'
+    }
+
+    api_response = requests.post(
+        URL,
+        data=body,
+        headers=headers,
+        verify=CERTFILE
+    )
+
+    try:
+        api_response.raise_for_status()
+    except requests.exceptions.HTTPError as err:
+        print(
+            'An HTTP {} Error Occured:{}'.format(
+                str(err),
+                api_response.text),
+            file=sys.stderr
+        )
+
+        return api_response.json()
+
+    try:
+        return api_response.json()['data']
+    except ValueError as err:
+        return {}
+
+
+def get_request_body(managed_object):
+    """Map a row in a csv to a nested dictionary
+    that SP will accept as a managed object
+
+    Args:
+        managed_object: flat dictionary from csv
+        representing a single managed object
+
+    Returns:
+        Nested dictionary representing a
+        managed object in SP
+
+    """
+
+    return {
+        'data': {
+            'attributes': {
+                'name': managed_object['name'],
+                'family': 'customer',
+                'match_type': 'cidr_block',
+                'match': managed_object['prefix'],
+                'tags': ['api']
+            },
+            'relationships': {
+                'mitigation_template': {
+                    'data': {
+                        'id': '2',
+                        'type': 'mitigation_template'
+                    }
+                }
+            }
+        }
+    }
+
+
+def get_managed_objects_from_csv(filename):
+    """ Get a handler for managed object data
+    from a csv file
+
+    Args:
+        filename: path / name for a csv file
+        containing managed_object configurations.
+        The first line of the csv is a header,
+        containing "name,prefix". Similarly,
+        subsequent lines represent managed objects.
+        E.g., "Wind,74.182.59.3/32".
+
+    Returns:
+        A generator returning managed objects in
+        nested dict form
+    """
+
+    with open(filename) as listings:
+        for row in csv.DictReader(listings):
+            yield get_request_body(row)
+
+
+def create_managed_object(leader, key, managed_object):
+    """ Crafts and makes an api request to create
+    an SP managed object
+
+    Args:
+        leader: hostname of an SP leader
+        key: api key, as generated by the
+             SP leader
+        managed_object: nested dict representing
+                        the managed_object being
+                        created
+
+    Returns:
+        Id as string of new managed object, or
+        None if request was unsuccessful
+    """
+
+    object_json = json.dumps(managed_object)
+
+    response = api_request(
+        'https://{}/api/sp/managed_objects/'.format(leader),
+        key,
+        object_json
+    )
+
+    if 'errors' in response:
+        print(
+            'Could not create managed object...',
+            file=sys.stderr
+        )
+        return None
+
+    return response["id"]
+
+
+def commit_config(leader, key):
+    """ Crafts and makes an api request to commit an
+        SP configuration
+
+    Args:
+        leader: hostname of an SP leader
+        key: api key, as generated by said SP leader
+
+    Returns:
+        boolean indicating the success of the
+        operation
+    """
+    print ("Committing configuration.")
+    commit_msg = json.dumps({
+        'data': {
+            'attributes': {
+                'commit_log_message':
+                    'Added managed objects to deployment via SP API'
+            }
+        }
+    })
+
+    response = api_request(
+        'https://{}/api/sp/config/'.format(leader),
+        key,
+        commit_msg
+    )
+
+    if 'errors' in response:
+        print(
+            "Could not commit configuration...",
+            file=sys.stderr
+        )
+        return False
+
+    print("Committed configuration.")
+    return True
+
+
+def main():
+    LEADER = "leader.example.com"
+    KEY = "eFvokphdyGHA_M4oLlLtfDnlIf9bpjFnn0mWlDqw"
+
+    for listing in get_managed_objects_from_csv('main.csv'):
+        create_managed_object(LEADER, KEY, listing)
+
+    commit_config(LEADER, KEY)
+
+
+if __name__ == "__main__":
+    main()

code-examples/README.md

@@ -0,0 +1,8 @@
+
+The files in this directory are included in the main document via
+org-mode `#INCLUDE:` directives.
+
+All source examples should be committed here, and then described and
+included in the document `sp-rest-api-tutorial.txt` so that when that
+is rendered as a PDF or HTML or ebook or whatever, the code is
+included and has been given some context.