Generating AAI API Docs

A&AI REST API Documentation

Generate the swagger like v8 to v11 spec via (thanks LiZi)

cd aai/aai-common/aai-core/
mvn -PgenerateXsd -DskipTests
mvn -PgenerateXsd install -DskipTests
mvn -PgenerateYaml install -DskipTests
mvn -PgenerateHtml install -DskipTests
cat ../aai-schema/src/main/resources/aai_swagger_html/aai_swagger_v8.html 
cat ../aai-schema/src/main/resources/aai_swagger_html/aai_swagger_v11.html


The Active and Available Inventory (AAI or A&AI) has its own REST API. 

The AAI REST API provides access to the AAI active inventory graph.  The API is largely configured from models and configuration files.  Each vertex in the graph has an API that can be called separately or, if part of a tree structure, as a nested element with one or more generations (parent, grandparent, and so on).

The edges of the graph are provisioned using a relationship list construct.  For PUT methods, a relationship contains the vertex type or category (related-to) and a list of relationship data which captures the key pieces of data required to uniquely identify the resource.  On a GET method, the above information and a URL are returned.  The URL can be used to GET all the details of that object.  The URL returned is suitable for retrying failed commands but should not be expected to be cacheable for very long periods (e.g., the version of the URL may get deprecated when the release changes).

API Definition

The API structure is composed of:

  • The HTTP command, which indicates the operation to perform
  • The HTTP URI, which defines what object this operation is related to
  • The HTTP version, which MUST be 1.1

Available HTTP commands are:

  • PUT: used to create or update an object
  • DELETE: used to delete an object or a set of objects
  • GET : used to query an object or set of objects
  • PATCH :  used to update specific fields owned by the client doing the update

The HTTP URI is built according to this pattern:

https://{serverRoot}/{namespace}/{resource}

  • (serverRoot} refers to the server base url: hostname+port+base path+version. Port and base path are OPTIONAL but AAI will use port 8443 and base path aai.  The first release version will be v8.
  • {namespace} refers to the API namespace. Supported namespaces are cloud-infrastructure, business, service-design-and-creation, and network
  • {resource} refers to how the object is identified according to the namespace specifications.

Example

GET https://{host-url}:8443/aai /v8/cloud-infrastructure/cloud-regions/cloud-region/{cloud-owner}/{cloud-region-id}

Postman example

Logs

aaiadmin@vm1-aai:/opt/app/aai/logs$ pwd

/opt/app/aai/logs

aaiadmin@vm1-aai:/opt/app/aai/logs$ cat ajsc-jetty/localhost_access.log

from VID portal

10.0.8.1 VID VID [05/Jul/2017:02:48:03 +0000] "GET /aai/v8/business/customers" 500 0 REST

10.0.8.1 VID VID [05/Jul/2017:02:48:16 +0000] "GET /aai/v8/service-design-and-creation/services" 500 0 REST

from a browser

32.60.102.40 AAI AAI [05/Jul/2017:14:46:48 +0000] "GET /aai/v8/service-design-and-creation/services" 400 0 REST




References

The full definition of the API can be found here: AAI REST API document. The API documentation generated from the schema (OXM file) can be found here: AAI REST API Specifications. The XSD generated from the schema can be found here: AAI schema.

  • No labels

7 Comments

  1. Guangrong Fu

    Hi,

    I have looked through the APIs. They're useful and helpful but somewhat abstract. Say I want to query the relationship between a VNF and a VM, what does the response data look like? According the description of the API, a <<relationship-data>> will be returned. Is it a single key-value pair or a list of key-value pairs? Could you please post an example response with some detailed information/data in it?

    Thanks.

  2. Michael O'Brien

    Guangrong, 

       These pages may not all be updated for 1.1 - this particular one is still 1.0 (v8) - you may get more info on the current 1.1/R1 page at Active and Available Inventory Project

    /michael

  3. undefined undefined

    The AAI REST API PDF document mentions that a PATCH does not require a resource-version. However, a resource-version is indeed needed to make a successful patch request. However, after the PATCH is complete the resource-versions are not changed. An example is below:

    curl -X PATCH \
      https://<IP>:<PORT>/aai/v8/business/customers/customer/Desjardins/service-subscriptions/service-subscription/SDWAN/service-instances/service-instance/8128c8ee-13f5-4f0b-9cf5-7932e32664fc \
      -H 'authorization: Basic QUFJOkFBSQ==' \
      -H 'cache-control: no-cache' \
      -H 'content-type: application/merge-patch+json' \
      -H 'postman-token: 42f70ace-f2db-a3a9-6f80-e46a65f5fa92' \
      -H 'x-fromappid: RASHMI' \
      -d '{
        "service-instance-id": "8128c8ee-13f5-4f0b-9cf5-7932e32664fc",
        "service-instance-location-id": "siteId",
        "resource-version": "1502393371",
        "metadata" : {
          "metadatum": [
                    {
                          "metaname":"test1",
                          "metaval":"testtest" ----> On first create doesn't require a resource-version. Include resource-version for this if you are updating it
                      },
                      {
                            "metaname":"test2",
                          "metaval":"testtest"
                      }
                ]
        }
    }'

    1. James Forsyth

      undefined undefined, I cannot reproduce this.  Using Postman, I was able to successfully PATCH a service instance, please see the following screenshots: 

      The documentation is correct, and users should not have to supply that attribute on PATCH requests.

      -jimmy


  4. René ROBERT

    "Reference" section on this page is deprecated compare to A&AI REST API Documentation

  5. Ullas Kumar K Y

    Hi, 

    As part of the SO API VNF Module creation, there is an async process . 

    POST /mso/WorkflowMessage/VNFAResponse/939ba1f2-67c5-417b-803f-80fdf5289b8c-1522947354911

    <vfModuleOutputs>
    <entry>
    <key>vVerifier_name</key>
    <value>Ex-vice_4_5_2018_VNF_MODULE_V1-vVerifier-32wmuzerbmk4</value>
    </entry>
    <entry>
    <key>vVerifier_ip</key>
    <value>10.50.1.107</value>
    </entry>
    </vfModuleOutputs>

    Can see the IP address of the VNF which was instantiated , but cannot get this information from AAI. Does this response gets added to AAI against VNF instance ? if so how can we get this?

    Thanks,

    Ullas

  6. Devanshu Tyagi

    Hi Folks,

    I am new to ONAP and have deployed ONAP using offline installer. Currently when I am using Curl GET request to aai service, I get Empty reply from server also when I ran demo init script to initialize Customer it failed.

    Could anyone guide what next steps I can do to identify the problem.

    Thanks,

    Devanshu