Guida all’integrazione

​

Guida all’integrazione

Questa pagina contiene informazioni su diversi strumenti e concetti fondamentali che dovresti conoscere quando integri gli endpoint dei membri della List nel tuo sistema. Abbiamo suddiviso la pagina in alcune sezioni:

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

​

Strumenti utili

Prima di addentrarci in alcuni concetti chiave che ti aiuteranno a integrare questo endpoint, ti consigliamo di familiarizzare con:

​

Postman

Postman è un ottimo strumento che puoi usare per testare un endpoint. Ogni richiesta Postman include tutti i parametri di path e di body per aiutarti a comprendere rapidamente ciò che è disponibile. Per ulteriori informazioni sulle nostre raccolte Postman, visita la pagina “Using Postman”. 

​

Esempi di codice

Vuoi iniziare a utilizzare questo endpoint con codice nel tuo linguaggio di programmazione preferito? Mettiamo a disposizione diversi esempi di codice che puoi usare come punto di partenza sulla nostra pagina GitHub.

​

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 fondamentali

​

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, OAuth 2.0 Authorization Code con PKCE o App only per autenticare le richieste agli endpoint di lookup delle List. Tuttavia, devi autenticarti con Contesto utente OAuth 1.0a o OAuth 2.0 per gli endpoint di manage delle List.

Contesto utente OAuth 1.0a, il che significa che devi usare un set di API Key e Access Token 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 Token per un altro utente, quest’ultimo deve autorizzare la tua App usando il flusso OAuth a 3 vie.

Tieni presente che OAuth 1.0a può essere complesso da usare. Se non conosci questo metodo di autenticazione, consigliamo di usare una libreria, utilizzare uno strumento come Postman oppure usare OAuth 2.0 o App only per autenticare le 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 consente di scegliere scope specifici e granulari che ti forniscono permessi specifici per conto di un utente.

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

App only richiede soltanto di includere un App only Access Token nella richiesta. Puoi generare un App only Access Token direttamente all’interno di un’App sviluppatore oppure generarne uno usando l’endpoint POST oauth2/token.

App only richiede soltanto di includere un App only Access Token nella richiesta. Puoi generare un App only Access Token direttamente all’interno di un’App sviluppatore oppure generarne uno usando 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 registrare un account sviluppatore, configurare un Project all’interno di tale account e creare un’App sviluppatore all’interno di quel Project. Potrai quindi trovare le tue chiavi e token nella tua App sviluppatore.  

​

Limiti di velocità

Ogni giorno, molte migliaia di sviluppatori inviano richieste alla X API. Per gestire l’elevato volume di queste richieste, sui limiti di velocità viene applicato a ciascun endpoint un limite al numero di richieste che puoi effettuare per conto della tua App o di un utente autenticato. 

Gli endpoint di consultazione (GET) sono soggetti a limiti di velocità sia a livello di App sia a livello di utente, mentre gli endpoint di gestione (POST/DELETE) sono limitati a livello di utente. Il limite a livello di App significa che tu, sviluppatore, puoi effettuare solo un certo numero di richieste a questo endpoint in un determinato periodo di tempo da una determinata App (utilizzando l’API Key e la Secret API Key, oppure l’App only Access Token). Il limite a livello di utente significa che l’utente autenticato per conto del quale stai effettuando la richiesta può eseguire una lookup di List solo un certo numero 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/members	GET	900 richieste per 15 minuti
/2/users/:id/list_memberships	GET	75 richieste per 15 minuti
/2/lists/:id/members	POST	300 richieste per 15 minuti
/2/lists/:id/members/:user_id	DELETE	300 richieste per 15 minuti

​

Campi ed expansions

L’endpoint GET di X API v2 consente agli utenti di selezionare con precisione quali data restituire dall’API utilizzando un insieme di strumenti chiamati fields ed expansions. Il parametro expansions consente di includere (espandere) gli oggetti referenziati nel payload. Ad esempio, la ricerca dei membri di una List consente di richiedere le seguenti expansions:

• pinned_tweet_id

Il parametro fields consente di selezionare esattamente quali fields all’interno dei diversi oggetti di data si desidera ricevere. La ricerca dei membri di una List restituisce principalmente oggetti utente. Per impostazione predefinita, l’oggetto utente restituisce i campi id, name e username. Per ricevere campi aggiuntivi come user.created_at o user.description, è necessario richiederli esplicitamente utilizzando il parametro user.fields. 

Abbiamo aggiunto una guida sull’uso di fields ed expansions.

Il prospetto seguente mostra i fields e le expansions disponibili per ciascun endpoint di lookup:

Endpoint	Fields	Expansions
/2/lists/:id/members	user.fields tweet.fields	pinned_tweet_id
/2/users/:id/list_memberships	list.fields user.fields	owner_id

​

Paginazione

La ricerca di membership/members può restituire una grande quantità di dati. Per garantire in ogni momento risultati coerenti e performanti, utilizziamo la paginazione. La paginazione è una funzionalità degli endpoint di X API v2 che restituiscono più risultati di quanti se ne possano includere in una singola risposta. Quando ciò accade, i campi data vengono restituiti in una serie di “pagine”. Scopri di più su come paginare i risultati.