Resync the API reference spec file

02 Nov 2024
5 Minutes To Read
Contributors

Print
Share
Dark mode
Light
PDF

Resync the API reference spec file

Updated On 02 Nov 2024
5 Minutes To Read
Contributors

Print
Share
Dark mode
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

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

Defaulttrue

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 | null

Resync response data

errors

Array of object (ApiErrorAndWarningsData) | null

Error log response

object

message

string | null

Descriptive message of the problem

pointer

string | null

Path where the problem occures

alerts

Array of object (ApiErrorAndWarningsData) | null

Alerts log response

object

message

string | null

Descriptive message of the problem

pointer

string | null

Path where the problem occures

categories_created

integer (int32)

Total categories created

articles_created

integer (int32)

Total articles created

extension_data

object | null

Extention data for customer API response

success

boolean

Status indication for customer API response

errors

Array of object (BaseError) | null

Errors in the customer API response

object

extension_data

object | null

Thids is the Extention data object

stack_trace

string | null

Stack trace for error response message

description

string | null

Description for error cause

error_code

string | null

Error code for Api response

custom_data

object | null

property*

warnings

Array of object (BaseWarning) | null

Warnings in the customer API response

object

extension_data

object | null

Extention Data for customer Api warning

description

string | null

Warning description

warning_code

string | null

warning code for customer Api base response

information

Array of object (BaseInformation) | null

Information passed by the customer API response

object

extension_data

object | null

Extention data for customer Api response information

description

string | null

status description for customer Api response information

400

Bad Request

Invalid project Version ID

Kindly ensure that the given project version ID is valid.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

extension_data

object | null

Extention data for customer API response

success

boolean

Status indication for customer API response

errors

Array of object (BaseError) | null

Errors in the customer API response

object

extension_data

object | null

Thids is the Extention data object

stack_trace

string | null

Stack trace for error response message

description

string | null

Description for error cause

error_code

string | null

Error code for Api response

custom_data

object | null

property*

warnings

Array of object (BaseWarning) | null

Warnings in the customer API response

object

extension_data

object | null

Extention Data for customer Api warning

description

string | null

Warning description

warning_code

string | null

warning code for customer Api base response

information

Array of object (BaseInformation) | null

Information passed by the customer API response

object

extension_data

object | null

Extention data for customer Api response information

description

string | null

status description for customer Api response information

Was this article helpful?

What's Next

Get all API reference logs