Guida all’integrazione

Questa pagina contiene informazioni su vari strumenti e concetti fondamentali da conoscere quando integri gli endpoint di lookup delle List nel tuo sistema. Abbiamo suddiviso la pagina in alcune sezioni:

• Strumenti utili
• Concetti chiave
• Autenticazione
• Developer portal, Project e App
• Limiti di velocità
• fields ed expansions
• Paginazione

​

Strumenti utili

Prima di approfondire alcuni concetti chiave che vi aiuteranno a integrare questo endpoint, consigliamo di familiarizzare con:

​

Postman

Postman è un ottimo strumento che puoi utilizzare per testare un endpoint. Ogni richiesta Postman include tutti i parametri di percorso e del body per aiutarti a capire rapidamente cosa è disponibile. Per ulteriori informazioni sulle nostre raccolte Postman, visita la pagina “Using Postman”. 

​

Esempi di codice

Vuoi iniziare a usare questo endpoint con codice nel tuo linguaggio di programmazione preferito? Sul nostro GitHub trovi diversi esempi di codice che puoi utilizzare come punto di partenza.

​

Librerie di terze parti

Sfrutta una delle librerie di terze parti della nostra community per iniziare. Puoi trovare una libreria compatibile con gli endpoint v2 cercando il tag di versione corretto.

​

Concetti chiave

​

Autenticazione

Tutti gli endpoint di X API v2 richiedono di autenticare le richieste con un set di credenziali, note anche come chiavi e token. Puoi utilizzare Contesto utente OAuth 1.0a, App only oppure OAuth 2.0 Authorization Code con PKCE per autenticare le richieste a questi endpoint. 

Contesto utente OAuth 1.0a, il che significa che è necessario utilizzare un set di API Key e Access Tokens utente per effettuare correttamente una richiesta. Gli access token devono essere associati all’utente per conto del quale stai effettuando la richiesta. Se desideri generare un set di Access Tokens per un altro utente, quest’ultimo deve autorizzare la tua App utilizzando il flusso OAuth a 3 vie.

Tieni presente che OAuth 1.0a può essere complesso da utilizzare. Se non hai familiarità con questo metodo di autenticazione, ti consigliamo di usare una libreria, uno strumento come Postman oppure OAuth 2.0 per autenticare le tue richieste.

OAuth 2.0 Authorization Code con PKCE consente un maggiore controllo sull’ambito di un’applicazione e flussi di autorizzazione su più dispositivi. OAuth 2.0 ti permette di selezionare scope specifici e granulati che ti conferiscono autorizzazioni precise per conto di un utente. 

Per abilitare OAuth 2.0 nella tua App, devi abilitarlo nelle impostazioni di autenticazione della tua App, nella sezione Impostazioni dell’App del developer portal.

App only richiede semplicemente che tu includa un App only Access Token nella richiesta. Puoi generare un token App only direttamente all’interno di un’App sviluppatore oppure generarne uno utilizzando l’endpoint POST oauth2/token.

​

Developer portal, Project e App sviluppatore

Per ottenere un set di credenziali di autenticazione compatibili con gli endpoint della X API v2, devi iscriverti a un account sviluppatore, configurare un Project all’interno di tale account e creare una developer App all’interno di quel Project. Potrai quindi trovare le tue chiavi e token all’interno della tua App sviluppatore.  

​

Limiti di velocità

Ogni giorno, molte migliaia di sviluppatori inviano richieste alla X API. Per gestire l’elevato volume di richieste, su ciascun endpoint vengono applicati limiti di velocità che limitano il numero di richieste effettuabili per conto della tua App o di un utente autenticato. 

Questi endpoint sono soggetti a limiti di velocità sia a livello di App sia a livello di utente. Il limite a livello di App significa che tu, sviluppatore, puoi effettuare solo un determinato numero di richieste a questo endpoint in un dato intervallo di tempo da una qualsiasi App (identificata tramite API Key e Secret API Key, oppure App only Access Token). Il limite a livello di utente significa che l’utente autenticato per conto del quale effettui la richiesta può eseguire una ricerca della List solo un numero limitato di volte su qualsiasi App sviluppatore.

La tabella seguente mostra i limiti di velocità per ciascun endpoint.

Endpoint	Metodo HTTP	Limite di velocità
/2/lists/:id	GET	75 richieste ogni 15 minuti
/2/users/:id/owned_lists	GET	15 richieste ogni 15 minuti

Fields and expansions

L’endpoint GET della X API v2 consente di selezionare esattamente quali dati ottenere dall’API utilizzando un insieme di strumenti chiamati fields e expansions. Il parametro expansions consente di includere in risposta gli oggetti referenziati nel payload. Ad esempio, cercando una List per ID puoi richiedere le seguenti expansions:

• owner_id

Il parametro fields consente di selezionare esattamente quali fields all’interno dei diversi oggetti dati desideri ricevere. Questi endpoint restituiscono principalmente oggetti List. Per impostazione predefinita, l’oggetto List restituisce i campi id e name. Per ricevere campi aggiuntivi come list.created_at o list.follower_count, devi richiederli esplicitamente utilizzando il parametro list.fields. 

Abbiamo aggiunto una guida sull’uso combinato di fields ed expansions nella nostra X API v2 data dictionary.

La tabella seguente mostra i fields e le expansions disponibili per questo gruppo di endpoint:

Endpoint	Fields	Expansions
/2/lists/:id	list.fields user.fields	owner_id
/2/users/:id/owned_lists	list.fields user.fields	owner_id

​

Paginazione

La consultazione delle List di proprietà dell’utente può restituire una grande quantità di dati. Per garantire risultati coerenti e performanti in qualsiasi momento, utilizziamo la paginazione. La paginazione è una funzionalità degli endpoint della X API v2 che restituiscono più risultati di quanti possano essere inclusi in una singola risposta. In questi casi, i dati vengono restituiti in una serie di “pagine”. Scopri di più su come eseguire la paginazione dei risultati.