Ανάπτυξη συσχετισμένων αντικειμένων

Τα αντικείμενα παραπέμπουν σε συσχετισμένα αντικείμενα μέσω ID: μια κάρτα έχει owner_id και collection_id. Όταν χρειάζεστε το ίδιο το συσχετισμένο αντικείμενο, δεν χρειάζεται να στείλετε δεύτερο αίτημα. Ζητήστε το με expand[] και θα έρθει στην ίδια απόκριση, μέσα στο expanded:

curl -G https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "expand[]=owner" \
  --data-urlencode "expand[]=collection"

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "owner_id": 7,
  "collection_id": 3,
  "expanded": {
    "owner": {"id": 7, "username": "anna", "display_name": "Anna Petrova", "role": "editor"},
    "collection": {"id": 3, "name": "support", "title": "Support"}
  }
}

Το παράδειγμα είναι συντομευμένο: ένα αναπτυγμένο αντικείμενο έχει όλα τα πεδία της δικής του λειτουργίας ανάγνωσης. Τα πεδία ID μένουν στη θέση τους, οπότε ο κώδικας που δεν χρησιμοποιεί expand[] βλέπει την ίδια απόκριση όπως πριν.

Αυτές οι λειτουργίες αναπτύσσουν συσχετισμένα αντικείμενα. Μια διαδρομή με τελεία αναπτύσσει μια συσχέτιση του αναπτυγμένου αντικειμένου, για παράδειγμα το collection.default_owner είναι ο προεπιλεγμένος υπεύθυνος της συλλογής της κάρτας.

Κάθε συσχέτιση έρχεται στη μορφή της λειτουργίας που διαβάζει το συσχετισμένο αντικείμενο:

Σε λίστες

Για μια λίστα, ξεκινήστε τη διαδρομή με data.: ισχύει για κάθε στοιχείο της σελίδας. Το ίδιο ισχύει για μια λίστα που επιστρέφει πίνακα, όπως το GET /v1/cards, και για μια λίστα που κρατά τα στοιχεία της σε ένα πεδίο, όπως το jobs του GET /v1/jobs ή το items του αρχείου καταγραφής παραδόσεων.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "expand[]=data.owner" \
  --data-urlencode "expand[]=data.collection"

Η Sursa φορτώνει κάθε συσχέτιση για ολόκληρη τη σελίδα με μία κίνηση, οπότε η ανάπτυξη μιας λίστας κοστίζει περίπου όσο ένα επιπλέον αίτημα και όχι ένα ανά στοιχείο. Ο δρομέας της επόμενης σελίδας δεν εξαρτάται από το expand[], οπότε στην επόμενη σελίδα μπορείτε να ζητήσετε άλλες συσχετίσεις.

Κανόνες

• Έως 10 διαδρομές ανά αίτημα, η καθεμία με βάθος έως 2 τμημάτων: data.owner σε μια λίστα, collection.default_owner σε ένα αντικείμενο.
• Μια άγνωστη διαδρομή, περισσότερες από 10 διαδρομές ή μια διαδρομή βαθύτερη από 2 τμήματα επιστρέφει 400 με τον κωδικό api.expand_invalid. Το details.path ονομάζει τη διαδρομή και το details.reason λέει τι είναι λάθος: unknown_path, too_deep ή too_many_paths.
• Ένα συσχετισμένο αντικείμενο αναπτύσσεται μόνο για πελάτη που θα μπορούσε να το διαβάσει με δικό του αίτημα. Το κλειδί χρειάζεται την εμβέλεια εκείνης της λειτουργίας: cards:read για κάρτες, συλλογές και φακέλους, users:read για χρήστες, webhooks:manage για συμβάντα. Το αντικείμενο πρέπει επίσης να είναι ορατό στον πελάτη, για παράδειγμα μέσα στις συλλογές ενός κλειδιού που είναι περιορισμένο σε ορισμένες συλλογές. Διαφορετικά η συσχέτιση αναπτύσσεται ως null και στο verifiers στη θέση του χρήστη βρίσκεται null. Το ID του επιστρέφεται κανονικά. Το folders περιέχει μόνο τους φακέλους που μπορεί να δει ο πελάτης.
• Ένα κλειδί προσαρμοσμένης πηγής δεν διαβάζει κάρτες, οπότε με αυτό το card ενός εγγράφου είναι πάντα null. Για να λάβετε την κάρτα, καλέστε το API αποστολής (push) με ένα κλειδί API που έχει τις εμβέλειες import:write και cards:read.
• Ένα συμβάν παλαιότερο από 30 ημέρες και το συμβάν μιας δοκιμαστικής παράδοσης αναπτύσσονται ως null.
• Το expand[] μόνο προσθέτει δεδομένα στην απόκριση. Δεν αλλάζει ποτέ τι κάνει το αίτημα.