getApiDocs() — MCP documentation tool

General Description

The getApiDocs operation provides general information about the GSB Entity Service API.

Detailed Description

This operation returns basic metadata about the API, including its name, version, and description. Unlike the getDocs operation, it does not include detailed documentation for individual operations. This is useful when you need a quick overview of the API without the detailed operation documentation.

Input Parameters

Parameter	Type	Required	Description
token	string	No	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Response

Success Response

{
    "success": true,
    "data": {
        "name": "GSB Entity Service API",
        "version": "string",
        "description": "API for managing entity data and definitions"
    }
}

Error Response

{
    "success": false,
    "error": "Error message describing what went wrong"
}

Example Usage

Get API Information

const result = await getApiDocs({
  token: "your-auth-token"
});

if (result.success) {
  const apiInfo = result.data;
  console.log(`API Name: ${apiInfo.name}`);
  console.log(`Version: ${apiInfo.version}`);
  console.log(`Description: ${apiInfo.description}`);
} else {
  console.error("Error:", result.error);
}

Check API Version

async function checkApiVersion(requiredVersion, token) {
  const result = await getApiDocs({ token });
  
  if (!result.success) {
    console.error("Error checking API version:", result.error);
    return false;
  }
  
  const currentVersion = result.data.version;
  
  // Compare versions (this is a simple string comparison)
  // For more complex version comparisons, consider using a version comparison library
  if (currentVersion === requiredVersion) {
    console.log(`API version ${currentVersion} matches required version ${requiredVersion}`);
    return true;
  } else {
    console.warn(`API version mismatch: current ${currentVersion}, required ${requiredVersion}`);
    return false;
  }
}

// Usage
const isCompatible = await checkApiVersion("1.0.0", "your-auth-token");
if (!isCompatible) {
  console.warn("This client may not be fully compatible with the current API version");
}

Display API Information in UI

import React, { useEffect, useState } from 'react';

function ApiInfoComponent({ token }) {
  const [apiInfo, setApiInfo] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    async function fetchApiInfo() {
      try {
        const result = await getApiDocs({ token });
        
        if (result.success) {
          setApiInfo(result.data);
        } else {
          setError(result.error);
        }
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }
    
    fetchApiInfo();
  }, [token]);
  
  if (loading) return <div>Loading API information...</div>;
  if (error) return <div>Error: {error}</div>;
  
  return (
    <div className="api-info">
      <h2>{apiInfo.name}</h2>
      <div className="version">Version: {apiInfo.version}</div>
      <p>{apiInfo.description}</p>
    </div>
  );
}

// Usage
<ApiInfoComponent token="your-auth-token" />

Additional Information

• The getApiDocs operation provides only general information about the API, not detailed documentation for individual operations.
• For detailed documentation on all operations, use the getDocs operation instead.
• This operation is lightweight and can be used for quick API version checks or displaying basic API information in a user interface.
• The API version information can be useful for client applications to ensure compatibility with the API.
• This operation requires minimal permissions and can typically be called with any valid authentication token.