Working with Resource Metadata

The REST API consists of a dynamic schema that is described by the metadata catalog. The metadata catalog serves as the API schema defining the contract, similarly to WSDL and XSD files in SOAP web services.

Using the metadata catalog, you can dynamically discover the API, including all available resources, the format and values of input and output, the supported HTTP methods and HTTP query parameters.

In NetSuite, records are the most important resource. The metadata catalog defines all available records, their fields, available values (for example, for enum fields), sublists and subrecords (both standard and custom ones), and their various properties. As new customizations are added to the system, they appear in the metadata catalog as well.

The metadata catalog describes the following properties of the REST API:

Names of records, fields, sublists, and subrecords
Field types
Reference fields and the referenced record types
Enum fields and their available internal values
Searchability of records, fields, sublists, and subrecords

The REST API comes with a fully personalized view on the resources (per user). This includes the ability to transparently work with user-specific NetSuite record customizations, such as custom records and fields. The ability to provide a record in its customized form means that the record structure can vary based on your specific NetSuite setup. Therefore, the REST API provides an option to dynamically generate metadata about the records (available resources and operations) in the form of standardized descriptions. Custom record metadata is accessible the same way as metadata for standard records.

Using metadata information, you can:

Get an overview of all available record types
Get an overview of the structure of a particular record type
Get an overview of searchable fields
Get an overview of supported HTTP methods and query parameters
Automatically generate client code, for example, API client libraries or client stubs.

REST web services provide metadata in Swagger (OpenAPI 3.0) and JSON Schema JSON-based formats. Both formats are used to define the structure of JSON data for validation, documentation, and interaction control.

The main difference between the two formats is that the metadata provided in JSON Schema format only describes the internal structure of a resource, for example, its fields, sublists, or subrecords.

In addition to this, the metadata in OpenAPI 3.0 format also describes links to related resources. It also describes how to interact with a resource through REST web services: it describes the URLs, HTTP methods, and parameters.

For more information, see the following help topics:

Related Topics