Οδηγίες απόκτησης API key στο theMovieDb.org

Η υπηρεσία themoviedb.org είναι μια βάση δεδομένων η οποία περιέχει πληροφορίες για πάνω από 430.000 ταινίες. Η πρόσβαση στην υπηρεσία μπορεί να γίνει, είτε μέσω της ιστοσελίδας https://www.themoviedb.org, είτε μέσω ενός ειδικού API (Application Programming Interface). To API είναι ένας κατάλογος λειτουργιών (operations) με τη μορφή web διευθύνσεων (Uniform Resource Identifiers – URIs) μαζί με τις παραμέτρους κλήσης αυτών (request parameters), καθώς και των αναμενόμενων απαντήσεων (responses), ακολουθώντας την αρχιτεκτονική REST. Συνήθως, η κλήση του API γίνεται από ένα άλλο σύστημα-πελάτης (client) που χρησιμοποιεί το API, για να συνδεθεί και να λάβει τις υπηρεσίες του themoviedb.org.  

Για τη χρήση του themoviedb.org θα πρέπει να δημιουργήσετε έναν λογαριασμό στο https://www.themoviedb.org  (αρκεί ένας λογαριασμός για κάθε ομάδα φοιτητών) ώστε να πάρετε ένα API KEY. Για τη δημιουργία του λογαριασμού αρχικά επιλέγετε το SIGN UP επάνω δεξιά

Εικόνα 1 – Κουμπί εγγραφής στο The Movie DB

Αφού δώσετε τα στοιχεία σας, θα αποσταλεί ένα e-mail επιβεβαίωσης που θα περιέχει σύνδεσμο τον οποίο πρέπει να χρησιμοποιήσετε ώστε να ενεργοποιήσετε τη σύνδεσή σας. Αφού συνδεθείτε, θα εμφανιστεί η εικόνα προφίλ επάνω δεξιά.

Αυτό που χρειάζεται για να γίνουν κλήσεις προς το API είναι ένα API KEY. To API KEY είναι απαραίτητο σε κάθε κλήση του API, ώστε να διασφαλιστεί ότι η σύνδεση γίνεται μόνο από τους εγγεγραμμένους χρήστες του συστήματος theMovieDb. Μετά τη λήψη του API KEY θα είστε σε θέση να καλείτε το API και να λαμβάνετε δεδομένα ταινιών.

Για τη δημιουργία του API, επιλέγουμε την εικόνα του λογαριασμού και από το πτυσσόμενο μενού επιλέγουμε Settings.

Εικόνα 2 – Μενού επιλογών προφίλ στο The Movie DB

Στη συνέχεια, από το μενού αριστερά επιλέγουμε API, μετά Create και μετά Developer:

Εικόνα 3 – Βήματα δημιουργίας API KEY

Στη συνέχεια, πρέπει να συμπληρωθεί μια φόρμα με κάποιες βασικές πληροφορίες. Συμπληρώστε τη φόρμα με τα στοιχεία σας, ενώ για τα υπόλοιπα στοιχεία χρησιμοποιείστε το παρακάτω υπόδειγμα (βλέπε Εικόνα 4):

Εικόνα 4 – Φόρμα απαραίτητων στοιχείων για τη δημιουργία API KEY

Με την επιτυχή υποβολή της φόρμας θα δημιουργηθεί το API KEY όπως φαίνεται στην Εικόνα 5.

Εικόνα 5 – API KEY και παράδειγμα χρήσης. Μας ενδιαφέρει μόνο το v3 auth

 

Η κλήση μιας λειτουργίας του API γίνεται με τη δημιουργία μιας web διεύθυνσης της παρακάτω μορφής:

operation_URI?parameter1=value1&parameter2=value2&...&parameter=valueN&api_key=xxx

όπου parameterX είναι μια παράμετρος της λειτουργίας και valueX η τιμή της παραμέτρου. Για τη χρήση του API, όπως αναφέραμε, απαιτείται το API KEY που δημιουργήσατε, το οποίο δίνεται σε κάθε κλήση και αποτελεί την τιμή της παραμέτρου api_key.

Για παράδειγμα για να πάρουμε μια λίστα με όλα τα είδη ταινιών θα χρησιμοποιήσουμε την παρακάτω κλήση:

https://api.themoviedb.org/3/genre/movie/list?api_key=ΤΟ_ΚΛΕΙΔΙ_ΕΔΩ

η οποία επιστρέφει όλες τις διαφορετικές κατηγορίες ταινιών που υπάρχουν στην παρακάτω μορφή:

{
  "genres": [
    {
      "id": 28,
      "name": "Action"
    },
...
    {
      "id": 37,
      "name": "Western"
    }
  ]
}

Αυτή η λίστα μας δίνει πληροφορίες οι οποίες θα χρησιμοποιηθούν για να δημιουργηθούν πιο ενδιαφέροντα ερωτήματα. Για παράδειγμα τώρα γνωρίζουμε πως η κατηγορία «Action movies» έχει id=28, συνεπώς μπορούμε να ρωτήσουμε ποιες ήταν οι Action Movies που κυκλοφόρησαν το έτος 2017 με το παρακάτω ερώτημα:

https://api.themoviedb.org/3/discover/movie?with_genres=28&primary_release_year=2017&language=el&api_key=ΤΟ_ΚΛΕΙΔΙ_ΕΔΩ

Το REST API είναι ένας πανίσχυρος μηχανισμός ο οποίος μας επιτρέπει να εκλεπτύνουμε σε μεγάλο βαθμό τα ερωτήματά μας. Μπορούμε για παράδειγμα να ταξινομήσουμε τις ταινίες του παραπάνω ερωτήματος σύμφωνα με τη δημοτικότητά τους:

https://api.themoviedb.org/3/discover/movie?with_genres=28&primary_release_year=2017&language=el&sort_by=popularity.desc&api_key=ΤΟ_ΚΛΕΙΔΙ_ΕΔΩ

Εικόνα 6 – Παράδειγμα αποτελεσμάτων ταινιών

Όλες οι απαντήσεις έρχονται σε μορφή JSON. Το JSON είναι ένας δομημένος τρόπος περιγραφής πληροφοριών που βασίζεται στη δομή του Map (βλέπε Εικόνα 7). Κάθε JSON Object αποτελείται από σύνολα Key-Value με δυνατότητα φωλιάσματος (nesting), όπου κάθε Value είναι άλλο JSON Object ή λίστα από Objects κ.ο.κ. Για καλύτερη κατανόηση της δομής JSON κειμένων μπορούν να χρησιμοποιηθούν και εργαλεία διαθέσιμα στο διαδίκτυο όπως το http://jsonviewer.stack.hu, τα οποία οπτικοποιούν τη δομή του αρχείου σε δεντρική μορφή.

Η γενική δομή του παραπάνω JSON αντικειμένου είναι η εξής:

Εικόνα 7 – Γενική δομή JSON Response για αποτελέσματα ταινιών

Βλέπουμε δηλαδή ότι σε πρώτο επίπεδο υπάρχει η ιδιότητα page η οποία αναφέρεται στο ποια σελίδα αποτελεσμάτων είναι η τρέχουσα (τα αποτελέσματα έρχονται με σελιδοποίηση – pagination). Στη συνέχεια ακολουθεί η ιδιότητα total_results με το πλήθος των αποτελεσμάτων και total_pages, με το πλήθος των σελίδων. Έπειτα, υπάρχει η λίστα ταινιών results με 20 ταινίες ανά page.

Παρατηρούμε πως τα JSON Objects περιέχονται μέσα στα σύμβολα { και }, ενώ οι λίστες περιέχονται μέσα στα σύμβολα [ και ] [1].

Αναπτύσσοντας  το πρώτο στοιχείο της λίστας βλέπουμε τη δομή στην Εικόνα 8. Υπάρχει μια πληθώρα ιδιοτήτων όπως vote_count, το id, ο τίτλος title της ταινίας αλλά και το vote_average και η ημερομηνία πρώτης προβολής release_date.

Εικόνα 8 – Ανάλυση της λίστας results σε πρώτο επίπεδο

This entry was posted in Useful. Bookmark the permalink.