A couple of general questions about the API

[#1]

Hello experts,

I only started to use the API recently with some success, and I got a couple of general questions. Hopefully, they are not too dumb!

1. How do you know what fields to include in the "_returned_fields"? Is there a way to show all the supported fields for an object?
2. What is the "_ref" field for in the response? Is it possible to generate a URI with it so we can open it in the browser to that object directly?

Thank you!

[#2]

Hi Difan,

1. We have a _schema parameter in the API URL which helps in understanding the object structure.

For e.g.: Let's consider "network" object 

        Step 1: Make the following API call:

curl -k --location --request GET 'https://<grid master ip/fqdn>/wapi/v2.12/network?_schema' \
--header 'Authorization: Basic YWRtaW46aW5mb2Jsb3g=' \
--header 'Content-Type: application/json'

        Step 2: The response will have details of all the supported fields by the given object (network in our example).

         Every object description contains a field called "supports" which can have values:

          - "s": searchable field

          - "r": readable field

          - "w": writable field

          - "u": updatable field 

        All the readable fields can be included in the "_return_fields" parameter. So, If the object has "r" in the "supports" section of "_schema" response then you can include it in your search. I have attached a sample response of "_schema" for your reference.

{"fields": .... {
            "is_array": false,
            "name": "comment",
            "searchable_by": ":=~",
            "standard_field": true,
            "supports": "rwus",        #check this key/value for the fields
            "type": [
                "string"
            ]
}..... }

        Step 3: Include the readable fields in your search:

curl -k --location --request GET 'https://<grid master ip/fqdn>/wapi/v2.12/network?_return_fields%2b=comment' \
--header 'Content-Type;' \
--header 'Authorization: Basic YWRtaW46aW5mb2Jsb3g=' \
--header 'Conntent-Type: application/json'

2. Each and every object in NIOS has a unique reference value which helps in the identification of the objects on the grid without any discrepancy. This unique value is stored in "_ref" field returned with the API response. 

It is not possible to generate a URI with the reference value for a browser activity. _ref value is specific to APIs only.

Hope this helps!! Please reach out if you need anything else.

Thanks and Regards

Vedant Sethia