specs

Creates, updates, deletes, gets or lists a specs resource.

Overview

Name	specs
Type	Resource
Id	google.apihub.specs

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
name	string	Identifier. The name of the spec. Format: projects/{project}/locations/{location}/apis/{api}/versions/{version}/specs/{spec}
attributes	object	Optional. The list of user defined attributes associated with the spec. The key is the attribute name. It will be of the format: projects/{project}/locations/{location}/attributes/{attribute}. The value is the attribute values associated with the resource.
contents	object	Optional. Input only. The contents of the uploaded spec. (id: GoogleCloudApihubV1SpecContents)
createTime	string (google-datetime)	Output only. The time at which the spec was created.
details	object	Output only. Details parsed from the spec. (id: GoogleCloudApihubV1SpecDetails)
displayName	string	Required. The display name of the spec. This can contain the file name of the spec.
documentation	object	Optional. The documentation of the spec. For OpenAPI spec, this will be populated from externalDocs in OpenAPI spec. (id: GoogleCloudApihubV1Documentation)
lintResponse	object	Optional. The lint response for the spec. (id: GoogleCloudApihubV1LintResponse)
parsingMode	string	Optional. Input only. Enum specifying the parsing mode for OpenAPI Specification (OAS) parsing.
sourceMetadata	array	Output only. The list of sources and metadata from the sources of the spec.
sourceUri	string	Optional. The URI of the spec source in case file is uploaded from an external version control system.
specType	object	The attribute values associated with resource. (id: GoogleCloudApihubV1AttributeValues)
updateTime	string (google-datetime)	Output only. The time at which the spec was last updated.

list

Successful response

Name	Datatype	Description
name	string	Identifier. The name of the spec. Format: projects/{project}/locations/{location}/apis/{api}/versions/{version}/specs/{spec}
attributes	object	Optional. The list of user defined attributes associated with the spec. The key is the attribute name. It will be of the format: projects/{project}/locations/{location}/attributes/{attribute}. The value is the attribute values associated with the resource.
contents	object	Optional. Input only. The contents of the uploaded spec. (id: GoogleCloudApihubV1SpecContents)
createTime	string (google-datetime)	Output only. The time at which the spec was created.
details	object	Output only. Details parsed from the spec. (id: GoogleCloudApihubV1SpecDetails)
displayName	string	Required. The display name of the spec. This can contain the file name of the spec.
documentation	object	Optional. The documentation of the spec. For OpenAPI spec, this will be populated from externalDocs in OpenAPI spec. (id: GoogleCloudApihubV1Documentation)
lintResponse	object	Optional. The lint response for the spec. (id: GoogleCloudApihubV1LintResponse)
parsingMode	string	Optional. Input only. Enum specifying the parsing mode for OpenAPI Specification (OAS) parsing.
sourceMetadata	array	Output only. The list of sources and metadata from the sources of the spec.
sourceUri	string	Optional. The URI of the spec source in case file is uploaded from an external version control system.
specType	object	The attribute values associated with resource. (id: GoogleCloudApihubV1AttributeValues)
updateTime	string (google-datetime)	Output only. The time at which the spec was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, apisId, versionsId, specsId		Get details about the information parsed from a spec. Note that this method does not return the raw spec contents. Use GetSpecContents method to retrieve the same.
list	select	projectsId, locationsId, apisId, versionsId	filter, pageSize, pageToken	List specs corresponding to a particular API resource.
create	insert	projectsId, locationsId, apisId, versionsId	specId	Add a spec to an API version in the API hub. Multiple specs can be added to an API version. Note, while adding a spec, at least one of contents or source_uri must be provided. If contents is provided, then spec_type must also be provided. On adding a spec with contents to the version, the operations present in it will be added to the version.Note that the file contents in the spec should be of the same type as defined in the projects/{project}/locations/{location}/attributes/system-spec-type attribute associated with spec resource. Note that specs of various types can be uploaded, however parsing of details is supported for OpenAPI spec currently. In order to access the information parsed from the spec, use the GetSpec method. In order to access the raw contents for a particular spec, use the GetSpecContents method. In order to access the operations parsed from the spec, use the ListAPIOperations method.
patch	update	projectsId, locationsId, apisId, versionsId, specsId	updateMask	Update spec. The following fields in the spec can be updated: * display_name * source_uri * lint_response * attributes * contents * spec_type In case of an OAS spec, updating spec contents can lead to: 1. Creation, deletion and update of operations. 2. Creation, deletion and update of definitions. 3. Update of other info parsed out from the new spec. In case of contents or source_uri being present in update mask, spec_type must also be present. Also, spec_type can not be present in update mask if contents or source_uri is not present. The update_mask should be used to specify the fields being updated.
delete	delete	projectsId, locationsId, apisId, versionsId, specsId		Delete a spec. Deleting a spec will also delete the associated operations from the version.
lint	exec	projectsId, locationsId, apisId, versionsId, specsId		Lints the requested spec and updates the corresponding API Spec with the lint response. This lint response will be available in all subsequent Get and List Spec calls to Core service.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
apisId	string
locationsId	string
projectsId	string
specsId	string
versionsId	string
filter	string
pageSize	integer (int32)
pageToken	string
specId	string
updateMask	string (google-fieldmask)

SELECT examples

get

Get details about the information parsed from a spec. Note that this method does not return the raw spec contents. Use GetSpecContents method to retrieve the same.

SELECT
name,
attributes,
contents,
createTime,
details,
displayName,
documentation,
lintResponse,
parsingMode,
sourceMetadata,
sourceUri,
specType,
updateTime
FROM google.apihub.specs
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND apisId = '{{ apisId }}' -- required
AND versionsId = '{{ versionsId }}' -- required
AND specsId = '{{ specsId }}' -- required;

list

List specs corresponding to a particular API resource.

SELECT
name,
attributes,
contents,
createTime,
details,
displayName,
documentation,
lintResponse,
parsingMode,
sourceMetadata,
sourceUri,
specType,
updateTime
FROM google.apihub.specs
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND apisId = '{{ apisId }}' -- required
AND versionsId = '{{ versionsId }}' -- required
AND filter = '{{ filter }}'
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

INSERT examples

create

Add a spec to an API version in the API hub. Multiple specs can be added to an API version. Note, while adding a spec, at least one of contents or source_uri must be provided. If contents is provided, then spec_type must also be provided. On adding a spec with contents to the version, the operations present in it will be added to the version.Note that the file contents in the spec should be of the same type as defined in the projects/{project}/locations/{location}/attributes/system-spec-type attribute associated with spec resource. Note that specs of various types can be uploaded, however parsing of details is supported for OpenAPI spec currently. In order to access the information parsed from the spec, use the GetSpec method. In order to access the raw contents for a particular spec, use the GetSpecContents method. In order to access the operations parsed from the spec, use the ListAPIOperations method.

INSERT INTO google.apihub.specs (
data__name,
data__displayName,
data__specType,
data__contents,
data__sourceUri,
data__lintResponse,
data__attributes,
data__documentation,
data__parsingMode,
projectsId,
locationsId,
apisId,
versionsId,
specId
)
SELECT 
'{{ name }}',
'{{ displayName }}',
'{{ specType }}',
'{{ contents }}',
'{{ sourceUri }}',
'{{ lintResponse }}',
'{{ attributes }}',
'{{ documentation }}',
'{{ parsingMode }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ apisId }}',
'{{ versionsId }}',
'{{ specId }}'
RETURNING
name,
attributes,
contents,
createTime,
details,
displayName,
documentation,
lintResponse,
parsingMode,
sourceMetadata,
sourceUri,
specType,
updateTime
;

Manifest

# Description fields are for documentation purposes
- name: specs
  props:
    - name: projectsId
      value: string
      description: Required parameter for the specs resource.
    - name: locationsId
      value: string
      description: Required parameter for the specs resource.
    - name: apisId
      value: string
      description: Required parameter for the specs resource.
    - name: versionsId
      value: string
      description: Required parameter for the specs resource.
    - name: name
      value: string
      description: >
        Identifier. The name of the spec. Format: `projects/{project}/locations/{location}/apis/{api}/versions/{version}/specs/{spec}`
        
    - name: displayName
      value: string
      description: >
        Required. The display name of the spec. This can contain the file name of the spec.
        
    - name: specType
      value: object
      description: >
        The attribute values associated with resource.
        
    - name: contents
      value: object
      description: >
        Optional. Input only. The contents of the uploaded spec.
        
    - name: sourceUri
      value: string
      description: >
        Optional. The URI of the spec source in case file is uploaded from an external version control system.
        
    - name: lintResponse
      value: object
      description: >
        Optional. The lint response for the spec.
        
    - name: attributes
      value: object
      description: >
        Optional. The list of user defined attributes associated with the spec. The key is the attribute name. It will be of the format: `projects/{project}/locations/{location}/attributes/{attribute}`. The value is the attribute values associated with the resource.
        
    - name: documentation
      value: object
      description: >
        Optional. The documentation of the spec. For OpenAPI spec, this will be populated from `externalDocs` in OpenAPI spec.
        
    - name: parsingMode
      value: string
      description: >
        Optional. Input only. Enum specifying the parsing mode for OpenAPI Specification (OAS) parsing.
        
      valid_values: ['PARSING_MODE_UNSPECIFIED', 'RELAXED', 'STRICT']
    - name: specId
      value: string

UPDATE examples

patch

Update spec. The following fields in the spec can be updated: * display_name * source_uri * lint_response * attributes * contents * spec_type In case of an OAS spec, updating spec contents can lead to: 1. Creation, deletion and update of operations. 2. Creation, deletion and update of definitions. 3. Update of other info parsed out from the new spec. In case of contents or source_uri being present in update mask, spec_type must also be present. Also, spec_type can not be present in update mask if contents or source_uri is not present. The update_mask should be used to specify the fields being updated.

UPDATE google.apihub.specs
SET 
data__name = '{{ name }}',
data__displayName = '{{ displayName }}',
data__specType = '{{ specType }}',
data__contents = '{{ contents }}',
data__sourceUri = '{{ sourceUri }}',
data__lintResponse = '{{ lintResponse }}',
data__attributes = '{{ attributes }}',
data__documentation = '{{ documentation }}',
data__parsingMode = '{{ parsingMode }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND apisId = '{{ apisId }}' --required
AND versionsId = '{{ versionsId }}' --required
AND specsId = '{{ specsId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
attributes,
contents,
createTime,
details,
displayName,
documentation,
lintResponse,
parsingMode,
sourceMetadata,
sourceUri,
specType,
updateTime;

DELETE examples

delete

Delete a spec. Deleting a spec will also delete the associated operations from the version.

DELETE FROM google.apihub.specs
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND apisId = '{{ apisId }}' --required
AND versionsId = '{{ versionsId }}' --required
AND specsId = '{{ specsId }}' --required;

Lifecycle Methods

lint

Lints the requested spec and updates the corresponding API Spec with the lint response. This lint response will be available in all subsequent Get and List Spec calls to Core service.

EXEC google.apihub.specs.lint 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@apisId='{{ apisId }}' --required, 
@versionsId='{{ versionsId }}' --required, 
@specsId='{{ specsId }}' --required;