Working with OpenAPI 3.0 Metadata
To get the metadata in OpenAPI 3.0 format, you have to specify the proper value in the Accept HTTP header. For OpenAPI 3.0, you must add a header in the format Accept: application/swagger+json.
To avoid the long loading time needed to gather OpenAPI 3.0 metadata for all records, the metadata catalog resource supports the select query parameter for selecting particular record types. You can use this parameter to restrict the metadata to certain record types only. In the following example, the request is modified to restrict the metadata to customer and sales order records only.
SET-HEADER Accept: application/swagger+json
GET https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/metadata-catalog?select=customer,salesorder
The following is an intentionally shortened response to the previous request.
"paths": {
"/salesorder": {
"get": {
"tags": [
"salesorder"
],
"summary": "Get list of records",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Search query used to filter results",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Get record",
"content": {
"application/vnd.oracle.resource+json; type=collection": {
"schema": {
"$ref": "#/components/schemas/salesorderCollection"
}
}
}
},
"default": {
"description": "Error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rest_error"
}
}
}
}
}
},
},
The response describes the structure of the records as well as the supported operations, HTTP methods, and query parameters.
The following image shows an excerpt from the response. It describes the record name, the query parameters, and the available HTTP methods you can use with the record.
The following excerpt describes the record structure and the properties of different fields: their name, type, format, and attributes.
The following excerpt describes a sublist of the sales order record.
The OpenAPI 3.0 record metadata received in the previous step can be used as input for any OpenAPI 3.0 compatible tool for further processing. For example, you can use the metadata in tools that generate REST client stubs as well as tools that specialize in dumping a static webpage that describes record structure. In this example, OpenAPI 3.0 metadata is used in the freely available online Swagger Editor for exploring the structure and operations that can be done with the customer and sales order records.
The performance of the online Swagger editor can be limited if there is a large amount of data to process. Therefore you shouldn't use the editor to generate metadata description for all exposed records.
By copy-pasting the example response to the Swagger Editor, you can see an output similar to the following:
Links to NetSuite records that are out of the scope of the select parameter are declared as generic JSON objects with no structure in the returned record metadata. You can avoid this by listing the referenced record in the select parameter.
From the graphic representation, you can see how to obtain a list of all customer and sales order records, how to create new record instances, and how to perform read, update, and delete operations upon them. You can expand each REST method for more description. The Swagger Editor output also contains a Schema section. The figure below shows how to use it to explore the structure of a record. For instance, you can see that the salesorder record contains the item sublist, represented in the form of salesorder-itemCollection that contains the totalResults, links, and items properties. The structure of a single line of the item sublist is then captured in the salesorder-itemElement part.
