SF API Topic and Action Enablement

SF API Topic and Action Enablement

Topic and Action Enablement Ruleset

This ruleset contains best practice for managing APIs enabled for topics and actions for agents.

Summary

WARNINGS:

Api should not have more than 30 operations (api-limit-number-operations )

it is recommended that operations enabled as agent actions have only one response code since only the first 2xx will be used. (operation-only-one-response-code)

VIOLATIONS:

topic mandatory extensions must be present and conform with patterns/count:
x-sfdc/agent/topic/classificationDescription (api-must-have-topic-classification-description) x-sfdc/agent/topic/scope (api-must-have-topic-scope)
x-sfdc/agent/topic/instructions and should have at least one item (api-must-have-topic-instruction) x-sfdc/agent/topic/name (api-must-have-topic-name) it should only contain letters, numbers, underscores and spaces (api-must-have-valid-topic-name)

Operations enabled for topic should have at least one operation enabled as action(operation-publish-topic-with-operations)

If an operation is enabled as an agent action (x-sfdc/agent/action/publishAsAgentAction set to true):
it must have at least one input (parameter or request body) (operation-must-have-input ) it must have at least one 2xx response (operation-must-have-2xx)
it must have a description longer than 10 characters (operation-must-have-descriptions) it must have operationId (operation-must-have-operation-id)
its payload con only have media type application/json (operation-supported-media-type) its responses can not have headers (operation-unsupported-response-headers)

• it's parameters, request and responses
  • can not use schema combination (schema-composition-not-supported-params, schema-composition-not-supported-request,schema-composition-not-supported-response)
  • must have descriptions (operation-parameters-must-have-descriptions, operation-request-must-have-description,operation-response-must-have-description)
  • can only be of types: String, Number, Integer, Boolean, String with date and Object (only-specific-types-params, only-specific-types-request, only-specific-types-response)
  • can not have nested objects (no-nested-object-params, no-nested-object-request,no-nested-object-response)
  • can not have additionalProperties (no-additional-properties,no-additional-properties-response)

If extension is defined it must be with true/false value
x-sfdc/privacy/isPii (element-is-pii) x-sfdc/agent/action/isDisplayable (operation-is-displayable)
x-sfdc/agent/action/isUserInput(operation-is-user-input) x-sfdc/agent/action/publishAsAgentAction(operation-publish-operation-as-agent-action)

Rules in this Ruleset

Violations

• api-must-have-topic-classification-description
• api-must-have-topic-instruction
• api-must-have-topic-name
• api-must-have-topic-scope
• api-must-have-valid-topic-name
• element-is-pii
• no-additional-properties
• no-additional-properties-response
• no-nested-object-params
• no-nested-object-request
• no-nested-object-response
• only-specific-types-params
• only-specific-types-request
• only-specific-types-response
• operation-is-displayable
• operation-is-user-input
• operation-must-have-2xx
• operation-must-have-descriptions
• operation-must-have-input
• operation-must-have-operation-id
• operation-parameters-must-have-descriptions
• operation-publish-operation-as-agent-action
• operation-publish-topic-with-operations
• operation-request-must-have-description
• operation-response-must-have-description
• operation-supported-media-type
• operation-unsupported-response-headers
• schema-composition-not-supported-params
• schema-composition-not-supported-request
• schema-composition-not-supported-response

Warnings

• api-limit-number-operations
• operation-only-one-response-code