Resync the API reference spec file
  • 25 Nov 2023
  • 4 Minutes to read
  • Contributors
  • Dark
    Light

Resync the API reference spec file

  • Dark
    Light

Article Summary

Put
/v2/APIReferences
Security
API Key
Header parameter nameapi_token
Enter REST API key. To generate a key, go to Settings → Knowledge base portal → API tokens
Body parameters
Resync API reference request

Resync an API reference with specific apiReferenceId projectVersionId, userId and a spec file url or a file type.

{
  "api_reference_id": "d2eafb73-ccb6-4d15-9c4a-959b3c232ddb",
  "project_version_id": "5b291e6b-fa40-4ab9-941e-f8fffc23b376",
  "user_id": "46f48bc7-760f-4b07-b2d2-fce4aa8ba234",
  "force_import": true,
  "url": "https://petstore.swagger.io/v2/swagger.json",
  "file": null
}
object
ApiReferenceId
string Required

The ID of the API reference

ProjectVersionId
string Required

The ID of the project version

UserId
string Required

The ID of the team account

ForceImport
boolean Required

true : The errors and alerts will not be shown while resyncing the spec file
false : The errors and alerts will be shown while resyncing the spec file

Default"True"
Url
string

Url of the spec file

File
string (binary)

File path of the spec file

Responses
200

Success

Success status Response

This is the sample response for single API reference resync with server variables.

{
  "data": {
    "errors": [],
    "alerts": [],
    "categories_created": 23,
    "articles_created": 23
  },
  "extension_data": null,
  "success": true,
  "errors": [],
  "warnings": [],
  "information": []
}
Success status Response with no server variables

This is the sample response for single API reference resync without server variables.

{
  "data": {
    "errors": [],
    "alerts": [],
    "categories_created": 3,
    "articles_created": 23
  },
  "extension_data": null,
  "success": true,
  "errors": [],
  "warnings": [
    {
      "extension_data": null,
      "description": "You may not be able to use try-it feature. Looks like server variables aren’t defined in your OpenAPI Specification file.",
      "warning_code": null
    }
  ],
  "information": []
}
Success status Response for ForceImport as false

This is the sample response for single API reference resync with force import as false.

{
  "data": {
    "errors": [
      {
        "message": "Declared path parameter 'contentId' needs to be defined as a path parameter at either the path or operation level",
        "pointer": "#/paths/~1v2~1Content~1{Id}~1version~1{contentCategoryId}/delete/parameters/2/in"
      }
    ],
    "alerts": [
      {
        "message": "Data and type mismatch found.",
        "pointer": "#/paths/~1v2~1Content/{Id}/depete/response/200/content/application~1json/examples/Content"
      }
    ],
    "categories_created": 3,
    "articles_created": 23
  },
  "extension_data": null,
  "success": true,
  "errors": [],
  "warnings": [],
  "information": []
}
Expand All
object
data
object (ApiDocsResyncDataCustomer)
errors
Array of object (ApiErrorAndWarningsData)

Error log response

object
message
string

Descriptive message of the problem

pointer
string

Path where the problem occures

alerts
Array of object (ApiErrorAndWarningsData)

Alerts log response

object
message
string

Descriptive message of the problem

pointer
string

Path where the problem occures

categories_created
integer (int32)

Total categories created

articles_created
integer (int32)

Total articles created

extension_data
object (ExtensionDataObject)
success
boolean

Status indication for customer API response

errors
Array of object (BaseError)

Errors in the customer API response

object
extension_data
object (ExtensionDataObject)
stack_trace
string

Stack trace for error response message

description
string

Description for error cause

error_code
string

Error code for Api response

custom_data
object
warnings
Array of object (BaseWarning)

Warning in the customer API response

object
extension_data
object (ExtensionDataObject)
description
string

Warning description

warning_code
string

warning code for customer Api base response

information
Array of object (BaseInformation)

Information passed by the customer API response

object
extension_data
object (ExtensionDataObject)
description
string

status description for customer Api response information

400

Bad Request

Invalid project Version ID

Kindly ensure that the given project version ID is valid.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "The supplied project version id d2eafb73-ccb6-4d15-9c4a-959b3c232ddba does not exist in your project",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}
Invalid API reference ID

Kindly ensure that the given API reference ID is valid.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "Api reference not found.",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}
Invalid user ID

Kindly ensure that the given user ID is valid.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "The user with id 'f11efc6f-e968-4e95-82eb-85ad61559de8a' does not exist in your project.",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}
Maximum API Reference limit reached

You have reached your maximum API reference limit, for continuing add a new version.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "Unable to add API Reference: Maximum API Reference limit reached",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}
Supplied URL is invalid

You have to provide a valid OAS spec file URL.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "Invalid Url",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}
Can`t upload both the file and the URL

You have to provide only a valid OAS spec file or a spec file URL.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "You can only upload URL or a spec file.",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}
Supplied file type is invalid

You have to upload a valid JSON or YAML file.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "Only YAML or JSON files are allowed.",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}
Expand All
object
data
object (ApiDocsResyncDataCustomer)
errors
Array of object (ApiErrorAndWarningsData)

Error log response

object
message
string

Descriptive message of the problem

pointer
string

Path where the problem occures

alerts
Array of object (ApiErrorAndWarningsData)

Alerts log response

object
message
string

Descriptive message of the problem

pointer
string

Path where the problem occures

categories_created
integer (int32)

Total categories created

articles_created
integer (int32)

Total articles created

extension_data
object (ExtensionDataObject)
success
boolean

Status indication for customer API response

errors
Array of object (BaseError)

Errors in the customer API response

object
extension_data
object (ExtensionDataObject)
stack_trace
string

Stack trace for error response message

description
string

Description for error cause

error_code
string

Error code for Api response

custom_data
object
warnings
Array of object (BaseWarning)

Warning in the customer API response

object
extension_data
object (ExtensionDataObject)
description
string

Warning description

warning_code
string

warning code for customer Api base response

information
Array of object (BaseInformation)

Information passed by the customer API response

object
extension_data
object (ExtensionDataObject)
description
string

status description for customer Api response information


Was this article helpful?