From 7a39af6828fd33c1a02dc3d8c05b9dd9084156e5 Mon Sep 17 00:00:00 2001 From: saengel Date: Sun, 17 Mar 2024 13:23:43 +0200 Subject: [PATCH] feat(API Docs): Add shape API --- openAPI.json | 512 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 512 insertions(+) diff --git a/openAPI.json b/openAPI.json index 2cb31f9e10..28eb6c7186 100644 --- a/openAPI.json +++ b/openAPI.json @@ -4879,6 +4879,479 @@ "required": true } ] + }, + "/api/shape/{title}": { + "summary": "Shape", + "description": "The shape API allows one to retrieve information about the shape of an Index on Sefaria. The shape refers some basic statistics about the Index, mostly the number of chapters, and the number of segments per chapter.", + "get": { + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShapeJSON" + }, + "examples": { + "Complex Text": { + "value": [ + { + "isComplex": true, + "section": "Haggadah", + "length": 38, + "chapters": [ + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, קדש", + "title": "Pesach Haggadah, Kadesh", + "length": 1, + "chapters": 13, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, ורחץ", + "title": "Pesach Haggadah, Urchatz", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, כרפס", + "title": "Pesach Haggadah, Karpas", + "length": 1, + "chapters": 3, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, יחץ", + "title": "Pesach Haggadah, Yachatz", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, הא לחמא עניא", + "title": "Pesach Haggadah, Magid, Ha Lachma Anya", + "length": 1, + "chapters": 3, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, מה נשתנה", + "title": "Pesach Haggadah, Magid, Four Questions", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, עבדים היינו", + "title": "Pesach Haggadah, Magid, We Were Slaves in Egypt", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, מעשה שהיה בבני ברק", + "title": "Pesach Haggadah, Magid, Story of the Five Rabbis", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, כנגד ארבעה בנים", + "title": "Pesach Haggadah, Magid, The Four Sons", + "length": 1, + "chapters": 5, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, יכול מראש חודש", + "title": "Pesach Haggadah, Magid, Yechol Me'rosh Chodesh", + "length": 1, + "chapters": 1, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, מתחילה עובדי עבודה זרה היו אבותינו", + "title": "Pesach Haggadah, Magid, In the Beginning Our Fathers Were Idol Worshipers", + "length": 1, + "chapters": 5, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, ארמי אבד אבי", + "title": "Pesach Haggadah, Magid, First Fruits Declaration", + "length": 1, + "chapters": 24, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, עשר המכות", + "title": "Pesach Haggadah, Magid, The Ten Plagues", + "length": 1, + "chapters": 20, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, דיינו", + "title": "Pesach Haggadah, Magid, Dayenu", + "length": 1, + "chapters": 16, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, פסח מצה ומרור", + "title": "Pesach Haggadah, Magid, Rabban Gamliel's Three Things", + "length": 1, + "chapters": 7, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, חצי הלל", + "title": "Pesach Haggadah, Magid, First Half of Hallel", + "length": 1, + "chapters": 4, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מגיד, כוס שניה", + "title": "Pesach Haggadah, Magid, Second Cup of Wine", + "length": 1, + "chapters": 4, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, רחצה", + "title": "Pesach Haggadah, Rachtzah", + "length": 1, + "chapters": 3, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מוציא מצה", + "title": "Pesach Haggadah, Motzi Matzah", + "length": 1, + "chapters": 4, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, מרור", + "title": "Pesach Haggadah, Maror", + "length": 1, + "chapters": 3, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, כורך", + "title": "Pesach Haggadah, Korech", + "length": 1, + "chapters": 4, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, שולחן עורך", + "title": "Pesach Haggadah, Shulchan Orech", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, צפון", + "title": "Pesach Haggadah, Tzafun", + "length": 1, + "chapters": 3, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, ברך, ברכת המזון", + "title": "Pesach Haggadah, Barech, Birkat Hamazon", + "length": 1, + "chapters": 23, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, ברך, כוס שלישית", + "title": "Pesach Haggadah, Barech, Third Cup of Wine", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, ברך, שפוך חמתך", + "title": "Pesach Haggadah, Barech, Pour Out Thy Wrath", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, הלל, מסיימים את ההלל", + "title": "Pesach Haggadah, Hallel, Second Half of Hallel", + "length": 1, + "chapters": 10, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, הלל, מזמורי הודיה", + "title": "Pesach Haggadah, Hallel, Songs of Praise and Thanks", + "length": 1, + "chapters": 6, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, הלל, כוס רביעית", + "title": "Pesach Haggadah, Hallel, Fourth Cup of Wine", + "length": 1, + "chapters": 4, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, חסל סידור פסח", + "title": "Pesach Haggadah, Nirtzah, Chasal Siddur Pesach", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, לשנה הבאה", + "title": "Pesach Haggadah, Nirtzah, L'Shana HaBaa", + "length": 1, + "chapters": 1, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, ויהי בחצי הלילה", + "title": "Pesach Haggadah, Nirtzah, And It Happened at Midnight", + "length": 1, + "chapters": 11, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, זבח פסח", + "title": "Pesach Haggadah, Nirtzah, Zevach Pesach", + "length": 1, + "chapters": 8, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, אדיר במלוכה", + "title": "Pesach Haggadah, Nirtzah, Ki Lo Na'e", + "length": 1, + "chapters": 9, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, אדיר הוא", + "title": "Pesach Haggadah, Nirtzah, Adir Hu", + "length": 1, + "chapters": 8, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, ספירת העומר", + "title": "Pesach Haggadah, Nirtzah, Sefirat HaOmer", + "length": 1, + "chapters": 2, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, אחד מי יודע", + "title": "Pesach Haggadah, Nirtzah, Echad Mi Yodea", + "length": 1, + "chapters": 1, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + }, + { + "section": "Haggadah", + "heTitle": "הגדה של פסח, נרצה, חד גדיא", + "title": "Pesach Haggadah, Nirtzah, Chad Gadya", + "length": 1, + "chapters": 10, + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + } + ], + "book": "Pesach Haggadah", + "heBook": "הגדה של פסח" + } + ] + }, + "Simple Text": { + "value": [ + { + "section": "Torah", + "heTitle": "שמות", + "title": "Exodus", + "length": 40, + "chapters": [ + 22, + 25, + 22, + 31, + 23, + 30, + 29, + 28, + 35, + 29, + 10, + 51, + 22, + 31, + 27, + 36, + 16, + 27, + 25, + 23, + 37, + 30, + 33, + 18, + 40, + 37, + 21, + 43, + 46, + 38, + 18, + 35, + 23, + 35, + 35, + 38, + 29, + 31, + 43, + 38 + ], + "book": "Exodus", + "heBook": "שמות" + } + ] + } + } + } + }, + "description": "Retrieve basic statistics and information about the \"shape\" of an `Index` on Sefaria. " + } + }, + "summary": "Shape", + "description": "Retrieve basic statistics and information about the \"shape\" of an `Index` on Sefaria. " + }, + "parameters": [ + { + "examples": { + "Tanakh": { + "value": "Jonah" + }, + "Talmud": { + "value": "Pesachim" + }, + "Commentary": { + "value": "Rashi on Exodus" + }, + "Category": { + "value": "Tanakh/Modern Commentary on Tanakh/Steinsaltz" + } + }, + "name": "title", + "description": "The title of a valid Sefaria `Index`, or the path of a valid Sefaria category. ", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + }, + { + "name": "depth", + "description": "The `depth` parameter in the query string indicates how many levels in the category tree to descend.\nIf `depth=0` is passed, then the returned JSON descends to end of tree.\nThe default is `depth=2`.", + "schema": { + "type": "integer" + }, + "in": "query" + }, + { + "name": "dependents", + "description": "The dependents parameter, if `true`, includes dependent texts. By default, they are filtered out.", + "schema": { + "type": "boolean" + }, + "in": "query", + "required": false + } + ] } }, "components": { @@ -12486,6 +12959,45 @@ "source_proj": true, "type": "text" } + }, + "ShapeJSON": { + "description": "The shape API allows one to retrieve information about the shape of an Index on Sefaria. The shape refers some basic statistics about the Index, mostly the number of chapters, and the number of segments per chapter.", + "required": [ + "Book", + "heBook", + "Chapters" + ], + "type": "object", + "properties": { + "Section": { + "description": "The parent section for this `Index`. (So for example, the `section` for `Jonah` is `Prophets`. The `section` for `Pesachim` is `Seder Moed`)", + "type": "string", + "example": "Prophets" + }, + "isComplex": { + "description": "A boolean representing whether or not this is a complex text. ", + "type": "boolean" + }, + "Length": { + "description": "The number of chapters or top-level sections in the `Index`. " + }, + "Book": { + "description": "Title of the `Index` in English", + "type": "string" + }, + "heBook": { + "description": "Title of the `Index` in Hebrew. ", + "type": "string" + }, + "Chapters": { + "description": "For simple texts, this is a list of chapter lengths. For complex texts or categories, the Shape API will return a list of dicts for each text within that category or text. ", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShapeJSON" + }, + "example": " \"chapters\": [\n 16,\n 11,\n 10,\n 11\n ]" + } + } } } }