Vai al contenuto principale

​
Coerenza tra gli endpoint della X API v2

Uno dei principali aspetti della nuova versione v2 della X API è la coerenza tra gli endpoint. Questo significa che gli oggetti restituiti, le funzionalità e i comportamenti dell’API sono uniformi tra endpoint simili. Puoi aspettarti che i seguenti elementi siano identici su tutti gli endpoint:

​
Denominazione dei percorsi

La denominazione dei percorsi include sempre la versione dell’endpoint, seguita dalla risorsa. Inoltre, il percorso può contenere un ID relativo alla risorsa precedente, un verbo di selezione che aiuta a determinare quali dati restituire (ad es. search o sample), un verbo di erogazione che indica come verranno forniti i dati (ad es. stream), oppure altre risorse che hanno una relazione con la risorsa principale (ad es. /user/12/tweets). Infine, è possibile aggiungere un parametro di query in coda se l’endpoint prevede parametri di query. Ecco alcuni esempi di come questi elementi di percorso e di query possono essere organizzati: /version/resource/id?param1=value&param2=value /version/resource/delivery/selection?param1=value&param2=value Esempi di richieste reali: /2/tweets/1067094924124872705?expansions=attachments.media_keys&tweet.fields=author_id /2/users/2244994945?user.fields=created_at,description /2/tweets/search/stream /2/tweets/search/recent?query=snow

​
Schema JSON

Le risposte alle richieste sono definite utilizzando JSON Schema. Questo implica che le richieste restituiscano in modo coerente insiemi di oggetti come array, con ogni elemento provvisto di un id. Le richieste non restituiscono mappe con l’id come chiave.

​
Oggetto di risposta e parametri

L’oggetto predefinito restituito è lo stesso per ogni endpoint di quel tipo di oggetto:
  • Gli id sono sempre stringhe.
  • I parametri e i campi della risposta utilizzano coerentemente l’ortografia dell’inglese americano.
  • I campi sono vuoti o non restituiti se non è presente alcun valore.
  • L’oggetto entities contiene solo le entità estratte dal testo del Post: include urls, hashtags, mentions e cashtags.
  • Tutte le informazioni relative alle card, inclusi i campi media_keys e poll_ids, sono restituite nell’oggetto attachments.
Ecco un esempio di oggetto di risposta dall’endpoint ricerca di un singolo Post (con il parametro tweet.fields impostato su author_id, entities): 
{
   "data": {
       "id": "1278747501642657792",
       "text": "È passato un anno dal lancio dei Twitter Developer Labs.\n\nMentre lavoriamo alla prossima generazione della #TwitterAPI (in arrivo PRESTO), scopri cosa abbiamo imparato e come siamo cambiati lungo il percorso. https://t.co/WvjuEWCa6G",
       "author_id": "2244994945",
       "entities": {
           "urls": [
               {
                   "start": 188,
                   "end": 211,
                   "url": "https://t.co/WvjuEWCa6G",
                   "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html",
                   "display_url": "blog.x.com/developer/en_u…",
                   "images": [
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=orig",
                           "width": 1600,
                           "height": 600
                       },
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=150x150",
                           "width": 150,
                           "height": 150
                       }
                   ],
                   "status": 200,
                   "title": "Un anno con Twitter Developer Labs: cosa abbiamo imparato e cosa è cambiato",
                   "description": "I Labs sono stati preziosi per aiutarci a capire cosa funziona bene e cosa no, cosa è piaciuto e cosa non è piaciuto."
                   "unwound_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html"
               }
           ],
           "hashtags": [
               {
                   "start": 106,
                   "end": 117,
                   "tag": "TwitterAPI"
               }
           ]
       }
   }
}

​
Autenticazione

Tutti gli endpoint di X API v2 richiedono l’autenticazione. Molti accettano il metodo OAuth 2.0 Bearer Token, che prevede l’invio di un Bearer Token insieme alla richiesta all’endpoint per completarla correttamente. Per gli endpoint che richiedono l’autorizzazione a creare, modificare o recuperare dati per conto di un altro utente, usare il Contesto utente OAuth 1.0a. Ciò implica fornire le API Key e i token della tua App sviluppatore, oltre a un set di Access Tokens utente generati per l’utente per conto del quale stai effettuando la richiesta. Il flusso OAuth a 3 vie può aiutarti a ottenere gli Access Tokens. Usa uno strumento o una libreria che compili automaticamente questa intestazione di autorizzazione. Ulteriori informazioni sono disponibili nella nostra documentazione sull’autenticazione.

​
Campi

L’oggetto restituito da ciascun endpoint è ridotto all’essenziale. Per consentire agli sviluppatori una maggiore personalizzazione della risposta dell’API, il parametro fields viene usato per richiedere i campi desiderati. I campi rimangono coerenti tra gli endpoint. L’Oggetto Post restituisce gli stessi campi in tutti gli endpoint in cui viene restituito l’Oggetto Post. Lo stesso set di campi può essere interrogato in endpoint simili. Ad esempio, gli stessi campi del Post possono essere interrogati in Posts lookup e per il Post fissato in alto espanso in Users lookup.

​
Espansioni

Quando opportuno, le expansions sono disponibili per tutti i campi id annidati (ad es. tutti i campi denominati *_id, come author_id). Le expansions sono disponibili anche per tutti i campi che hanno un id che non è l’identificatore di livello superiore dell’oggetto corrente. Ad esempio, nella ricerca dei Post, il Post è l’oggetto corrente con il campo id come identificatore di livello superiore. I campi author_id o referenced_tweets.id possono essere espansi in oggetti utente o in Oggetti Post completi aggiungendo questi valori separati da virgola al parametro expansions. Ti preghiamo di segnalare eventuali incongruenze che noti in relazione a questi campi.
⌘I