REST Resource: organizations.sites.apidocs

Resource: ApiDoc

ApiDoc represents an API catalog item. Catalog items are used in two ways in a portal:

  • Users can browse and interact with a visual representation of the API documentation
  • The apiProductName field provides a link to a backing API product. Through this link, portal users can create and manage developer apps linked to one or more API products.
JSON representation
{
  "siteId": string,
  "id": string,
  "title": string,
  "description": string,
  "published": boolean,
  "anonAllowed": boolean,
  "apiProductName": string,
  "requireCallbackUrl": boolean,
  "imageUrl": string,
  "categoryIds": [
    string
  ],
  "modified": string,
  "visibility": boolean,
  "edgeAPIProductName": string,
  "specId": string,
  "graphqlSchema": string,
  "graphqlEndpointUrl": string,
  "graphqlSchemaDisplayName": string
}
Fields
siteId

string

Output only. The ID of the parent portal.

id

string (int64 format)

Output only. The ID of the catalog item.

title

string

Required. The user-facing name of the catalog item. title must be a non-empty string with a max length of 255 characters.

description

string

Optional. Description of the catalog item. Max length is 10,000 characters.

published

boolean

Optional. Denotes whether the catalog item is published to the portal or is in a draft state. When the parent portal is enrolled in the audience management feature, the visibility can be set to public on creation by setting the anonAllowed flag to true or further managed in the management UI (see Manage the visibility of an API in your portal) before it can be visible to any users. If not enrolled in the audience management feature, the visibility is managed by the anonAllowed flag.

anonAllowed

boolean

Optional. Boolean flag that manages user access to the catalog item. When true, the catalog item has public visibility and can be viewed anonymously; otherwise, only registered users may view it. Note: when the parent portal is enrolled in the audience management feature, and this flag is set to false, visibility is set to an indeterminate state and must be explicitly specified in the management UI (see Manage the visibility of an API in your portal). Additionally, when enrolled in the audience management feature, updates to this flag will be ignored as visibility permissions must be updated in the management UI.

apiProductName

string

Required. Immutable. The name field of the associated API product. A portal may have only one catalog item associated with a given API product.

requireCallbackUrl

boolean

Optional. Whether a callback URL is required when this catalog item's API product is enabled in a developer app. When true, a portal user will be required to input a URL when managing the app (this is typically used for the app's OAuth flow).

imageUrl

string

Optional. Location of the image used for the catalog item in the catalog. This can be either an image with an external URL or a file path for image files stored in the portal, for example, /files/book-tree.jpg. When specifying the URL of an external image, the image won't be uploaded to your assets; additionally, loading the image in the integrated portal will be subject to its availability, which may be blocked or restricted by content security policies. Max length of file path is 2,083 characters.

categoryIds[]

string

Optional. The IDs of the API categories to which this catalog item belongs.

modified

string (int64 format)

Output only. Time the catalog item was last modified in milliseconds since epoch.

visibility

boolean

Optional. DEPRECATED: use the published field instead

edgeAPIProductName

string

Optional. Immutable. DEPRECATED: use the apiProductName field instead

specId
(deprecated)

string

Optional. DEPRECATED: DO NOT USE

graphqlSchema
(deprecated)

string

Optional. DEPRECATED: manage documentation through the getDocumentation and updateDocumentation methods

graphqlEndpointUrl
(deprecated)

string

Optional. DEPRECATED: manage documentation through the getDocumentation and updateDocumentation methods

graphqlSchemaDisplayName
(deprecated)

string

Optional. DEPRECATED: manage documentation through the getDocumentation and updateDocumentation methods

Methods

create

Creates a new catalog item.

delete

Deletes a catalog item.

get

Gets a catalog item.

getDocumentation

Gets the documentation for the specified catalog item.

list

Returns the catalog items associated with a portal.

update

Updates a catalog item.

updateDocumentation

Updates the documentation for the specified catalog item.