Skip to content

Latest commit

 

History

History
262 lines (190 loc) · 7.83 KB

docs-portal-management.md

File metadata and controls

262 lines (190 loc) · 7.83 KB

Docs Portal Management

const docsPortalManagementController = new DocsPortalManagementController(client);

Class Name

DocsPortalManagementController

Methods

Publish Hosted Portal

Publish artifacts for a Hosted Portal.

This endpoint regenerates all the artifacts for a hosted portal and uploads them to APIMatic's cloud storage, from where the Portal fetches them. These artifacts include:

  1. SDKs
  2. Docs
  3. API Specification files

Call this endpoint to update your Hosted Portal after you update an API Entity via any of the Import API Endpoints.

Note: If you have an embedded portal against the same API Entity, artifacts for that portal will get updated as well.

async publishHostedPortal(
  apiEntityId: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<void>>

Parameters

Parameter Type Tags Description
apiEntityId string Template, Required The ID of the API Entity to update the portal artifacts for.
requestOptions RequestOptions | undefined Optional Pass additional request options.

Response Type

void

Example Usage

const apiEntityId = '5f87f8ab9615d38a2eb990ca';
try {
  const { result, ...httpResponse } = await docsPortalManagementController.publishHostedPortal(apiEntityId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Publish Embedded Portal

Publish artifacts for an Embedded Portal and get the Portal Embed script.

This endpoint regenerates all the artifacts for an embedded portal and uploads them to APIMatic's cloud storage, from where the Portal fetches them. These artifacts include:

  1. SDKs
  2. Docs
  3. API Specification files

Call this endpoint to update your Embedded Portal after you update an API Entity via any of the Import API Endpoints. This endpoint returns the Portal Embed script in the response.

Note: If you have a hosted portal against the same API Entity, artifacts for that portal will get updated as well.

async publishEmbeddedPortal(
  apiEntityId: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<void>>

Parameters

Parameter Type Tags Description
apiEntityId string Template, Required The ID of the API Entity to update the portal artifacts for.
requestOptions RequestOptions | undefined Optional Pass additional request options.

Response Type

void

Example Usage

const apiEntityId = '5f87f8ab9615d38a2eb990ca';
try {
  const { result, ...httpResponse } = await docsPortalManagementController.publishEmbeddedPortal(apiEntityId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Generate On-Prem Portal Via API Entity

Generate an On-premise Documentation Portal for an API Entity. This endpoint generates all artifacts for the Portal and packages them together into a zip file along with the required HTML, CSS and JS files. The generated artifacts include:

  1. SDKs
  2. Docs
  3. API Specification files

The endpoint returns a zip file that contains a static Site and can be hosted on any Web Server.

async generateOnPremPortalViaAPIEntity(
  apiEntityId: string,
  accept: Accept3,
  requestOptions?: RequestOptions
): Promise<ApiResponse<void>>

Parameters

Parameter Type Tags Description
apiEntityId string Template, Required The ID of the API Entity to generate the Portal for.
accept Accept3 Header, Required -
requestOptions RequestOptions | undefined Optional Pass additional request options.

Response Type

void

Example Usage

const apiEntityId = '5f87f8ab9615d38a2eb990ca';
const accept = 'application/zip';
try {
  const { result, ...httpResponse } = await docsPortalManagementController.generateOnPremPortalViaAPIEntity(apiEntityId, accept);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Generate On-Prem Portal Via Build Input

Generate an On-premise Documentation Portal by uploading a Portal Build Input. This endpoint generates all artifacts for the Portal and packages them together into a zip file along with the required HTML, CSS and JS files. The generated artifacts include:

  1. SDKs
  2. Docs
  3. API Specification files

The endpoint returns a zip file that contains a static Site and can be hosted on any Web Server.

async generateOnPremPortalViaBuildInput(
  file: FileWrapper,
  requestOptions?: RequestOptions
): Promise<ApiResponse<NodeJS.ReadableStream | Blob>>

Parameters

Parameter Type Tags Description
file FileWrapper Form, Required The input file to the Portal Generator. Must contain the build file.
requestOptions RequestOptions | undefined Optional Pass additional request options.

Response Type

NodeJS.ReadableStream | Blob

Example Usage

const contentType = null;
const file = new FileWrapper(fs.createReadStream('dummy_file'));
try {
  const { result, ...httpResponse } = await docsPortalManagementController.generateOnPremPortalViaBuildInput(file);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Errors

HTTP Status Code Error Description Exception Class
400 Bad Request ApiError
401 Unauthorized ApiError
402 Subscription Issue ApiError
422 Unprocessable Entity ApiError

Unpublish Portal

Unpublish a Hosted or Embedded Portal published for an API Entity. Calling this endpoint deletes all the published artifacts for a Portal from APIMatic's cloud storage.

In case of a Hosted Portal, to completely remove the Portal, this endpoint needs to be called against all API versions that the Portal hosts.

In case of an Embedded Portal, to completely remove the Portal, the user needs to manually remove the Portal Embed script from the embedding site.

async unpublishPortal(
  apiEntityId: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<void>>

Parameters

Parameter Type Tags Description
apiEntityId string Template, Required The ID of the API Entity to unpublish the Portal artifacts for.
requestOptions RequestOptions | undefined Optional Pass additional request options.

Response Type

void

Example Usage

const apiEntityId = '5f87f8ab9615d38a2eb990ca';
try {
  const { result, ...httpResponse } = await docsPortalManagementController.unpublishPortal(apiEntityId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}