Response definitions for R2 apis

src/service/R2/commonTypes.js

@@ -0,0 +1,27 @@
+/**
+ * Access control list for OSDU records
+ * @typedef {Object} OsduAccessControlList 
+ * @property {string[]} viewers - Users and groups that can view the record
+ * @property {string[]} owners - Users and groups that own the record
+ */
+
+/**
+ * Legal information for OSDU records
+ * @typedef {Object} OsduLegalInformation 
+ * @property {string[]} legaltags - Legal tags associated with the record
+ * @property {string[]} otherRelevantDataCountries - Other countries associated with the data that are legally relevant
+ * @property {string} status - The legal status of the record's data
+ */
+
+/**
+ * Single record returned by a query result
+ * @typedef {Object} OsduRecord
+ * @property {Object.<string,string>} data - Freeform data for the record. Refer to schema definitions for available properties
+ * @property {string} kind - Schema that the record conforms to
+ * @property {string} namespace - Grouping that schema comes from
+ * @property {OsduLegalInformation} legal - Legal information for the record. Refer to schema definitions for available properties
+ * @property {string} id - Record identifier
+ * @property {OsduAccessControlList} acl - Access control list
+ * @property {string} type - Record type
+ * @property {number} version - The version of this record
+ */

src/service/R2/delivery.js

@@ -17,11 +17,24 @@ class OsduR2DeliveryService extends OsduR2BaseService {
     constructor(osdu_client, data_partition) {
         super(osdu_client, data_partition);
     }
-
+
+    /**
+     * Individual processed file
+     * @typedef {Object} ProcessedFile
+     * @property {string} signedUrl - The signed url to retrieve this file
+     * @property {string} unsignedUrl - The storage url for the file that does not have presigned permissions
+     * @property {string} kind - The kind for this file
+     */
+    /**
+     * Response to delivery of requested files
+     * @typedef {Object} SignedUrls
+     * @property {Object.<string,ProcessedFile>} processed - Dictionary of processed file
+     * @property {string[]} unprocessed - List of srns for the files that have not been processed
+     */
     /**
      * Get signed urls for the data file underlying the specified OSDU File records
      * @param {string[]} srns - SRN identifiers of the files for which you wish to retrieve signed urls
-     * @returns {Object} The API Response
+     * @returns {SignedUrls} The API Response
      */
     async getSignedUrls(srns) {
         return await this._client.post(`/api/delivery/v2/GetFileSignedUrl`, { srns }, this._dataPartition);

src/service/R2/legal.js

@@ -17,66 +17,102 @@ class OsduR2LegalService extends OsduR2BaseService {
     constructor(osdu_client, data_partition) {
         super(osdu_client, data_partition);
     }
+
+    /**
+     * Legal tag properties
+     * @typedef {Object} LegalTagProperties
+     * @property {string[]} countryOfOrigin
+     * @property {string} contractId
+     * @property {string} expirationDate
+     * @property {string} originator
+     * @property {string} dataType
+     * @property {string} securityClassification
+     * @property {string} personalData
+     * @property {string} exportClassification
+     */
+    /**
+     * Legal tag model
+     * @typedef {Object} LegalTag
+     * @property {string} name - Name identifier for the legal tag
+     * @property {string} description - Brief description of what the legal tag represents
+     * @property {LegalTagProperties} properties - Properties of the legal tag
+     */
+    /**
+     * Response to retieval of multiple legal tags
+     * @typedef {Object} LegalTagList
+     * @property {LegalTag[]} legalTags - List of available legal tags
+     */
 
     // TODO: Define response types
     /**
      * Get all supported legal tags in the given data partition
-     * @returns {Object} The API Response
+     * @returns {LegalTagList} The API Response
      */
     async listLegalTags() {
         return await this._client.get(`/api/legal/v1/legaltags`, this._dataPartition);
     }
     /**
      * Get requested legal tags in the given data partition
      * @param {string[]} names - The list of tag names you wish to retrieve
-     * @returns {Object} The API Response
+     * @returns {LegalTagList} The API Response
      */
     async getLegalTags(names) {
         return await this._client.post(`/api/legal/v1/legaltags:batchRetrieve`, { names }, this._dataPartition);
     }
+    /**
+     * Legal tag model
+     * @typedef {Object} InvalidLegalTag
+     * @property {string} name - Name identifier for the legal tag
+     * @property {string} reason - Reason why the legal tag is invalid
+     */
+    /**
+     * Response to retieval of multiple legal tags
+     * @typedef {Object} ValidateLegalTagsResponse
+     * @property {InvalidLegalTag[]} invalidLegalTags - List of invalid legal tags
+     */
     /**
      * Validate requested legal tags in the given data partition
      * @param {string[]} names - The list of tag names you wish to validate
-     * @returns {Object} The API Response
+     * @returns {ValidateLegalTagsResponse} The API Response
      */
     async validateLegalTags(names) {
         return await this._client.post(`/api/legal/v1/legaltags:validate`, { names }, this._dataPartition);
     }
     /**
      * Retrieve a specific legal tag in the given data partition
      * @param {string} name - The name of the tag you wish to retrieve
-     * @returns {Object} The API Response
+     * @returns {LegalTag} The API Response
      */
     async getLegalTag(name) {
         return await this._client.get(`/api/legal/v1/legaltags/${name}`, this._dataPartition);
     }
     /**
      * List the allowed legal tag properties and values in the given data partition
-     * @returns {Object} The API Response
+     * @returns {Object.<string,Object.<string,string>|string>} The API Response
      */
     async getLegalTagProperties() {
         return await this._client.get(`/api/legal/v1/legaltags:properties`, this._dataPartition);
     }
     /**
      * Create a new legal tag in the given data partition
      * @param {Object} tagData - The JSON representation of the tag you wish to create
-     * @returns {Object} The API Response
+     * @returns {LegalTag} The API Response
      */
     async createLegalTag(tagData) {
         return await this._client.get(`/api/legal/v1/legaltags`, tagData, this._dataPartition);
     }
     /**
      * Update an existing legal tag in the given data partition
      * @param {Object} tagData - The JSON representation of the tag you wish to update
-     * @returns {Object} The API Response
+     * @returns {LegalTag} The API Response
      */
     async updateLegalTag(tagData) {
         return await this._client.put(`/api/legal/v1/legaltags`, tagData, this._dataPartition);
     }
     /**
      * Delete an existing legal tag in the given data partition
      * @param {string} tagData - The name of the tag you wish to delete
-     * @returns {Object} The API Response
+     * @returns {number} The API Response
      */
     async deleteLegalTag(name) {
         return await this._client.delete(`/api/legal/v1/legaltags/${name}`, this._dataPartition);

src/service/R2/query.js

@@ -18,10 +18,25 @@ class OsduR2QueryService extends OsduR2BaseService {
         super(osdu_client, data_partition);
     }
 
+    /**
+     * Results for particular aggregation grouping within the given query
+     * @typedef {Object} OsduAggregationItem
+     * @property {string} key - Identifier for the aggregation
+     * @property {number} count - Number of items that match this aggregation key
+     */
+    /**
+     * Response to OSDU query
+     * @typedef {Object} OsduQueryResults
+     * @property {OsduRecord[]} results - List of query result records
+     * @property {OsduAggregationItem[]|null} aggregations - List of aggregated records
+     * @property {number} totalCount - Total number of records matched by the query
+     * @property {string} [cursor] - Page marker to resume query at next page
+     */
+
     /**
      * Get OSDU records that match the given query constraints
      * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder}
-     * @returns {Object} The API Response
+     * @returns {OsduQueryResults} The API Response
      */
     async query(query_params) {
         if (!query_params.offset) {
@@ -33,7 +48,7 @@ class OsduR2QueryService extends OsduR2BaseService {
      * Get OSDU records that match the given query constraints
      * - Allow specification of a cursor for paged queries
      * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder}
-     * @returns {Object} The API Response
+     * @returns {OsduQueryResults} The API Response
      */
     async queryWithPaging(query_params, cursor) {
         if (!query_params.limit) {
@@ -50,7 +65,7 @@ class OsduR2QueryService extends OsduR2BaseService {
      * - Will page internally and aggregate results until no more pages are found
      * - Note that this may make multiple network requests if multiple pages are found
      * @param {Object} query_params - Query parameters built using the [OsduQueryBuilder]{@link OsduQueryBuilder}
-     * @returns {Object} The API Response
+     * @returns {OsduQueryResults} The API Response
      */
     async queryAll(query_params) {
         var output = {

src/service/R2/storage.js

@@ -20,10 +20,17 @@ class OsduR2StorageService extends OsduR2BaseService {
 
     // Records
     // TODO: Define response types
+    /**
+     * API response for GetRecords
+     * @typedef {Object} OsduGetRecordsResponse
+     * @property {OsduRecord[]} records - List of valid records
+     * @property {string[]} invalidRecords - List of IDs for invalid records
+     * @property {string[]} retryRecords - List of records that failed to retrieve and should be retried
+     */
     /**
      * Get OSDU records for the specified ids
      * @param {string[]} record_ids - Record identifiers of the OSDU records to retrieve
-     * @returns {Object} The API Response
+     * @returns {OsduGetRecordsResponse} The API Response
      */
     async getRecords(record_ids) {
         return await this._client.post(`/api/storage/v2/query/records`, {
@@ -33,15 +40,21 @@ class OsduR2StorageService extends OsduR2BaseService {
     /**
      * Get OSDU records for the specified id
      * @param {string} record_id - Record identifier of the OSDU record to retrieve
-     * @returns {Object} The API Response
+     * @returns {OsduRecord} The API Response
      */
     async getRecord(record_id) {
         return await this._client.get(`/api/storage/v2/records/${record_id}`, this._dataPartition);
     }
+    /**
+     * API response for GetRecordVersions
+     * @typedef {Object} GetRecordVersionsResponse
+     * @property {string} recordId - The id of the record requested
+     * @property {number[]} versions - Available versions for this record 
+     */
     /**
      * Get OSDU record versions for the specified id
      * @param {string} record_id - Record identifier of the OSDU record to retrieve version data
-     * @returns {Object} The API Response
+     * @returns {GetRecordVersionsResponse} The API Response
      */
     async getRecordVersions(record_id) {
         return await this._client.get(`/api/storage/v2/records/versions/${record_id}`, this._dataPartition);
@@ -50,68 +63,87 @@ class OsduR2StorageService extends OsduR2BaseService {
      * Get OSDU record for the specified id at the specified version
      * @param {string} record_id - Record identifier of the OSDU record to retrieve
      * @param {string} version - Version id to retrieve
-     * @returns {Object} The API Response
+     * @returns {OsduRecord} The API Response
      */
     async getRecordVersion(record_id, version) {
         return await this._client.get(`/records/${record_id}/${version}`, this._dataPartition);
     }
+    /**
+     * API response for StoreRecords
+     * @typedef {Object} OsduStoreRecordsResponse
+     * @property {number} recordCount - Number of records stored
+     * @property {string[]} recordIds - IDs of the records stored
+     * @property {string[]} skippedRecordIds - IDs of records skipped and not stored
+     */
     /**
      * Upsert the provided records
      * @param {Object[]} records - List of JSON representations of the records to upsert
-     * @returns {Object} The API Response
+     * @returns {OsduStoreRecordsResponse} The API Response
      */
     async storeRecords(records) {
         return await this._client.post(`/api/storage/v2/records`, records, this._dataPartition)
     }
     /**
      * Delete OSDU record
      * @param {string} record_id - Record identifier of the OSDU record to delete
-     * @returns {Object} The API Response
+     * @returns {number} The API Response
      */
     async deleteRecord(record_id) {
         return await this._client.delete(`/api/storage/v2/records/${record_id}`, this._dataPartition);
     }
 
-    // Manifest
+    // Schemas
     /**
-     * Ingest a manifest containing linked records
-     * @param {Object} manifest - JSON representation of the manifest to process and ingest
-     * @returns {Object} The API Response
+     * API response to QueryAllKinds
+     * @typedef {Object} OsduQueryAllKindsResponse
+     * @property {string|null} cursor - Marker to resume query for all kinds from end of this query
+     * @property {string[]} results - List of available kinds
      */
-    async ingestManifest(manifest) {
-        return await this._client.post(`/api/storage/v2/manifest`, manifest, this._dataPartition);
-    }
-
-    // Schemas
     /**
      * Retrieve a list of all supported record kinds
      * @returns {Object} The API Response
+     * @param {number} [limit=100] - The maximum number of kinds to return (up to 100)
+     * @param {string} [cursor=""] - Marker to resume query for all kinds from end of previous query
      */
-    async queryAllKinds() {
-        return await this._client.get(`/api/storage/v2/query/kinds`, this._dataPartition);
+    async queryAllKinds(limit = 100, cursor = "") {
+        return await this._client.get(`/api/storage/v2/query/kinds?limit=${limit}${cursor ? `&cursor=${cursor}` : ''}`, this._dataPartition);
     }
+    /**
+     * Property definition for an OSDU schema
+     * @typedef {Object} OsduSchemaProperty
+     * @property {string} path - Flat path to access the property
+     * @property {string} kind - Type of the property
+     * @property {Object} ext - Extensions
+     */
+    /**
+     * API response to GetSchema
+     * @typedef {Object} OsduGetSchemaResponse
+     * @property {string} kind - Name of the kind for this schema
+     * @property {OsduSchemaProperty[]} schema - List of schema properties
+     * @property {OsduSchemaProperty[]|null} ext - List of extension properties
+     */
     /**
      * Get OSDU schema for a given kind
      * @param {string} kind - Name of the kind to retrieve the schema
-     * @returns {Object} The API Response
+     * @returns {OsduGetSchemaResponse} The API Response
      */
     async getSchema(kind) {
         return await this._client.get(`/api/storage/v2/schemas/${kind}`, this._dataPartition);
     }
     /**
      * Create a new schema to register a new kind
      * @param {string} kind - Name of the new kind to create
-     * @param {Object} schema - JSON representation of the kind's schema
-     * @param {Object} ext - JSON representation of the schema extensions
-     * @returns {Object} The API Response
+     * @param {OsduSchemaProperty[]} schema - JSON representation of the kind's schema
+     * @param {OsduSchemaProperty[]|null} ext - JSON representation of the schema extensions
+     * @returns {number} The API Response. 201 for successful creation
      */
     async createSchema(kind, schema, ext) {
         return await this._client.post(`/api/storage/v2/schemas`, { kind, schema, ext }, this._dataPartition);
     }
     /**
      * Delete a kind and it's associated schema
      * @param {string} kind - Name of the kind to delete
-     * @returns {Object} The API Response
+     * @returns {number} The API Response. 204 for successful deletion
      */
     async deleteSchema(kind) {
         return await this._client.delete(`/api/storage/v2/schemas/${kind}`, this._dataPartition);