Seguire gli standard di codifica

Quando crei un connettore personalizzato, segui queste best practice nel codice.

Definizione API

apiDefinition.swagger.json, noto anche come swagger, è il punto in cui viene definito il comportamento del connettore.

  • Rientro: usa soft tab con quattro spazi. Non usare hard tab.
  • Rimuovi lo spazio finale: lo spazio finale include tutti gli spazi vuoti che si trovano alla fine di una riga, se non seguito da altri caratteri. Un hard tab è considerato come uno spazio finale se non seguito da altri caratteri.

Struttura del file

Per ottenere una definizione di swagger leggibile, crea una definizione API con la seguente struttura:

  1. Versione SwaggerOpenAPI (attualmente, è supportata solo la versione 2.0)
  2. Informazioni sul connettore (titolo, descrizione, stato, contatti)
  3. Schemi host e supportati
  4. Sezione Consumes/Produces
  5. Percorsi (definizioni di azioni e trigger)
  6. Definizioni (tipi di dati usati in azioni e trigger)
  7. Parametri (parametri che possono essere usati nelle operazioni)

Azioni e trigger

Usa Pascal Casing per operationId: tutte le parole in lettere maiuscole (inclusa la prima). Non aggiungere trattini (-) o caratteri di sottolineatura (_) per separare le parole.

  • Bene

    "operationId": "GetMessages",

  • Non valido

    "operationId": "getMessages",
"operationId": "Get-Messages",
"operationId": "Get_Messages",

Riepilogo e descrizione

Le operazioni dovrebbero sempre essere associate a un riepilogo e una descrizione. Il riepilogo sarà il nome dell'operazione, dovrà dunque essere breve e preciso, la descrizione deve fornire maggiori informazioni e terminare con un punto (.).

La maggior parte delle descrizioni è inserita come suggerimenti nelle caselle dei parametri. Assicurati di immettere un testo breve e significativo. Descrizioni e riepiloghi non devono avere lo stesso contenuto.

  • Bene

    "summary": "List Name",
"description": "The list to check for messages.",

  • Non valido

    "summary": "List",
"description": "List.",

RISPOSTE

Definisci il tuo codice di riuscita usando un tipo di risposta HTTP 2xx. Non usare default come unica risposta definita, ma abbinalo a una definizione di riuscita. Se possibile, elenca anche le risposte 4xx/5xx note.

  • Usa gli errori di tipo 4xx quando il problema ha avuto origine sul lato client, ecco alcuni esempi:

    • 401 - The username is invalid (it can only contain lowercase letters and numbers)

  • Usa gli errori di tipo 5xx quando il problema ha avuto origine sul lato server

    • 504 - The request timed-out

  • Bene

    {
  "responses": {
    "200": {
      "description": "OK",
      "schema": {
        "$ref": "#/definitions/Message"
      }
    },
    "400": {
      "description": "Bad Request"
    },
    "404": {
      "description": "Not Found"
    },
    "401": {
      "description": "Unauthorized"
    },
    "403": {
      "description": "Forbidden"
    },
    "500": {
      "description": "Internal Server Error. Unknown error occurred"
    },
    "default": {
      "description": "Operation Failed."
    }
  }
}

  • Non valido

    {
  "responses": {
    "default": {
      "description": "OK",
      "schema": {
        "type": "string"
      }
    }
  }
}

Definizioni e parametri

Per i parametri che appaiono in più operazioni, crea un parametro name nella sezione parameters anziché definire questo parametro in ogni operazione che lo usa.

  • Bene

    In questo esempio il parametro id è definito in IdInPath e usato nelle operazioni GetMemberGroups e RemoveMemberFromGroup.

    {
  "paths": {
    "/groups/{id}/getMemberGroups": {
      "post": {
        "summary": "Get groups of a user",
        "description": "Get the groups a user is a member of.",
        "operationId": "GetMemberGroups",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    },
    "/groups/{id}/members/{memberId}/delete": {
      "delete": {
        "summary": "Remove member",
        "description": "Delete a member from a group.",
        "operationId": "RemoveMemberFromGroup",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          },
          {
            "name": "memberId",
            "in": "path",
            "required": true,
            "description": "The Id of the member to be deleted.",
            "x-ms-summary": "Member Id",
            "type": "string"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    }
  },
  // definitions
  "parameters":{
    "IdInPath": {
      "name": "id",
      "in": "path",
      "description": "Unique identifer of a group (Ex. 'id_group1').",
      "required": true,
      "x-ms-summary": "Group Id",
      "type": "string"
    },
  }
}

    L'uso di riferimenti su parametri e definizioni renderà ApiDefinition più gestibile. Ad esempio, l'aggiornamento della descrizione eventualmente necessario verrà eseguito in un'unica posizione, anziché in tutte le operazioni che la usano.

  • Non valido

    {
  "paths": {
    "/groups/{id}/getMemberGroups": {
      "post": {
        "summary": "Get groups of a user",
        "description": "Get the groups a user is a member of.",
        "operationId": "GetMemberGroups",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Unique identifer of a group (Ex. 'id_group1').",
            "required": true,
            "x-ms-summary": "Group Id",
            "type": "string"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    },
    "/groups/{id}/members/{memberId}/delete": {
      "delete": {
        "summary": "Remove member",
        "description": "Delete a member from a group.",
        "operationId": "RemoveMemberFromGroup",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Unique identifer of a group (Ex. 'id_group1').",
            "required": true,
            "x-ms-summary": "Group Id",
            "type": "string"
          },
          {
            "name": "memberId",
            "in": "path",
            "required": true,
            "description": "The Id of the member to be deleted.",
            "x-ms-summary": "Member Id",
            "type": "string"
          }
        ],
        "responses": {
          // response definitions
        }
      }
    }
  }
}

Crea una voce sulle definizioni e usa tale riferimento in tutte le operazioni che hanno la stessa risposta di oggetto.

  • Bene

    In questo esempio oltre a usare un parametro a cui si fa riferimento, le operazioni GetUser e UpdateUser fanno riferimento alla stessa risposta dell'oggetto UserResponse, definita una volta nella sezione definitions.

    {
  "paths": {
    "/v1.0/users/{id}": {
      "get": {
        "summary": "Get user",
        "description": "Get details for a user.",
        "operationId": "GetUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        }
      },
      "patch": {
        "summary": "Update user",
        "description": "Update the info for a user.",
        "operationId": "UpdateUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "201": {
            "description": "Accepted",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        },
        "deprecated": false,
        "x-ms-no-generic-test": true
      }
    },
  },
  // definitions
  "definitions":{
   "UserResponse": {
      "type": "object",
      "properties": {
        "id": {
          "description": "The unique identifier for the user.",
          "type": "string",
          "x-ms-summary": "Id"
        },
        "email": {
          "description": "The email associated to the user.",
          "type": "string",
          "x-ms-summary": "Email"
        },
        // more fields here
      }
    }
  }
}

  • Non valido

    {
  "paths": {
    "/v1.0/users/{id}": {
      "get": {
        "summary": "Get user",
        "description": "Get details for a user.",
        "operationId": "GetUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        }
      },
      "patch": {
        "summary": "Update user",
        "description": "Update the info for a user.",
        "operationId": "UpdateUser",
        "parameters": [
          {
            "$ref": "#/parameters/IdInPath"
          }
        ],
        "responses": {
          "201": {
            "description": "Accepted",
            "schema": {
              "$ref": "#/definitions/UserResponse"
            }
          }
        },
        "deprecated": false,
        "x-ms-no-generic-test": true
      }
    },
  },
  // definitions
  "definitions":{
   "UserResponse": {
      "type": "object",
      "properties": {
        "id": {
          "description": "The unique identifier for the user.",
          "type": "string",
          "x-ms-summary": "Id"
        },
        "email": {
          "description": "The email associated to the user.",
          "type": "string",
          "x-ms-summary": "Email"
        },
        // more fields here
      }
    }
  }
}

Fornire commenti

L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.

  • Last updated on