MLS Apps RESTful API Protocol

Έκδοση 0.1

Το τμήμα ανάπτυξης της MLS (MLS RnD Lab) έχει δημιουργήσει ένα RESTful API για να επιτρέψει σε προγραμματιστές να έχουν πρόσβαση στις υπηρεσίες αυτής. Οι υπηρεσίες περιλαμβάνουν ανοιχτά δεδομένα τα οποία προσφέρονται σε όλους αλλά και τη σύνδεση σε συγκεκριμένες εφαρμογές μέσω αυθεντικοποίησης.

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

Βασική Δομή

Response Template:
{
	"head":{
		"protocol":"MAP",
		"version":"MAP/0.1",
		"protocol_description":"MLS Apps API Protocol",
		"status":1,
		"locale":"en_US",
		"timezone":"Europe/Athens",
		"time":1421428172,
		"time_float":1421428172.183
	},
	"body":{
		"key1":{
			"type":"json",
			"context":{}
		},
		"key2":{
			"type":"json",
			"context":{}
		}
	}
}

Παραπάνω βλέπουμε ένα παράδειγμα μιας απάντησης μιας υπηρεσίας η οποία επιστρέφει ένα API Response. Περιλαμβάνει όλες τις πληροφορίες στο πεδίο header, οι οποίες συνοδεύουν κάθε απάντηση και περιέχουν πληροφορίες σχετικά με την κλήση όπως το πρωτόκολλο και την έκδοσή του, την ώρα της κλήσης, τη γλώσσα και τη ζώνη ώρας αναφορικά με τα οποία είναι τα δεδομένα. Το πιο σημαντικό πεδίο είναι το πεδίο status το οποίο υποδεικνύει εάν η κλήση ήταν επιτυχής ή παρουσιάστηκε κάποιο σφάλμα. Σε περίπτωση μη αυθεντικοποίησης, η τιμή του status γίνεται 0.

Το πεδίο body περιλαμβάνει δεδομένα ανάλογα με την υπηρεσία που απαντάει. Όπως βλέπουμε στο παράδειγμα, η κάθε απάντηση έχει συγκεκριμένη δομή η οποία αποτελείται από το όνομα της απάντησης (key1), τον τύπο της απάντησης (key1.type) ο οποίος μπορεί να είναι json, html, xml κλπ. και το περιεχόμενο της απάντησης (key1.context).

Ασφάλεια και κλειδιά

Ορισμένες υπηρεσίες θα δηλώνουν ότι χρειάζονται ασφάλεια για την πρόσβασή τους από εγγεγραμμένους χρήστες. Για αυτές τις υπηρεσίες απαιτείται από τον χρήστη η δημιουργία κλειδιών αυθεντικοποίησης με σκοπό την επιπρόσθετη ασφάλεια της επικοινωνίας και των δεδομένων με σκοπό να αυθεντικοποιείται η εφαρμογή και να έχει πρόσβαση στις υπηρεσίες.

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

Παράδειγμα χρήσης

[ANY Request]: https://mlsapps.gr/subs/api/[any_service]

Parameters:
[app_id]: The application id
[key]: The authentication key

[GET Request Example]: https://mlsapps.gr/subs/api/test.php?app_id=421321&key=16388d931b93c8883ac87f2658afac9e

If there is error in authentication:
{
	"head":{
		"protocol":"MAP",
		"version":"MAP/0.1",
		"protocol_description":"MLS Apps API Protocol",
		"status":0,
		"locale":"en_US",
		"timezone":"Europe/Athens",
		"time":1421428172,
		"time_float":1421428172.183
	},
	"body":{
		"error":{
			"type":"json",
			"context":"Authentication Error"
		}
	}
}

Η διαχείριση κλειδιών γίνεται από τη σελίδα ρυθμίσεων του χρήστη, στο τμήμα Διαχείρισης Κλειδιών. Τα κλειδιά ασφαλείας πρέπει να κρατιούνται κρυφά και να μην εμφανίζονται σε δημόσια κομμάτια κώδικα όπως ο κωδικός πρόσβασης του χρήστη ώστε να μην υπάρχει μη εξουσιοδοτημένη πρόσβαση.

MLS Apps™ © 2018Κέντρο ΒοήθειαςΕλληνικά