MelTravelz/apls_json_contract.md

## apls_json_contract.md

      
    Raw
  

              apls_json_contract.md
            
          
    JSON Contract: ALPs (Advanced Language Practices)


Get the Homepage / UsersController#index

GET "/api/v1/users"

Response:
Status: 200
{
  "data": [{
    "id": "55",
    "type": “user",
    "attributes": {
        "name": "Deniz",
        "preferred_lang": "Turkish"
    }},
   {
    "id": "1",
    "type": “user",
    "attributes": {
        "name": "Alexis",
        "preferred_lang": "Spanish"
      }
   }]
}


Get a User's Dashboard / UsersController#show

GET "/api/v1/users/:id"

Response:
Status: 200
{
  "data": {
    "id": “55”,
    "type": “user",
    "attributes": {
        "name": "Deniz",
        "preferred_lang": "Turkish",
        "challenges": [
            {
              "challenge_id": "1", 
              "language": "Turkish", 
              "verb": "(i) gitmek",
              "eng_verb": "to go", 
              "image_url": "/random/unplash/image.url",
              "image_alt_text": "Plane flying over the Bosphorous", 
              "created_at": "05/30/2023"
            }, 
            { ...etc...}
        ]
     }  
   }
}


Get a Challenge Prompt / Users/ChallengesController#new

GET "/api/v1/users/:user_id/challenges/new"

Response:
Status: 200
{
  "data": {
    "id": null,
    "type": “prompt",
    "attributes": {
        "user_id": = "55",
        "language": "Turkish", 
        "verb": "(i) gitmek",
        "eng_verb": "to go",
        "image_url": "/random/unplash/image.url",
        "image_alt_text": "Plane flying over the Bosphorous",
        "grammar_points": [
           {
            "grammar_point": "şimdiki zaman (-iyor)",
            "eng_grammar_point": "present/present continuous tense"
           },
           {
            "grammar_point": "geniş zaman (-ir/-er)",
            "eng_grammar_point": "simple present tense"
            }
        ]
     }  
   }
}


Submit a Challenge Response / Users/ChallengesController#create

POST "/api/v1/users/:user_id/challenges"

Request Body:
{
 "language": "Turkish",
 "verb": "(i) gitmek",
 "eng_verb": "to go",
 "image_url": "/random/unplash/image.url",
 "image_alt_text": "Plane flying over the Bosphorous", 
 "sentences": [
   {
    "grammar_point": "şimdiki zaman (-iyor)",
    "eng_grammar_point": "present/present continuous tense",
    "user_sent": "Bu yaz Hopa'ya gidiyorum." --> correct sentence <--
    },
    {
      "grammar_point": "geniş zaman (-ir/-er)",
      "eng_grammar_point": "simple present tense",
      "user_sent": "Biz her yillar biz Fethiye'ye giderim." --> incorrect sentence <--
    }
  ]
}

Response:
Status: 201
{
  "data": {
    "id": “1”,
    "type": “challenge"
   }
}


Get a Challenge Show Page / Users/ChallengesController#show

GET "/api/v1/users/:user_id/challenges/:id"

Response:
Status: 200
{
  "data": {
    "id": “1”,
    "type": “challenge",
    "attributes": {
        "user_id": = "55",
        "language": "Turkish", 
        "verb": "(i) gitmek",
        "eng_verb": "to go", 
        "image_url": "/random/unplash/image.url",
        "image_alt_text": "Plane flying over the Bosphorous", 
        "created_at": "05/30/2023",
        "grammar_points": null,
        "sentences": [
          {
           "id": "1",
           "grammar_point": "şimdiki zaman (-iyor)",
           "eng_grammar_point": "present/present continuous tense",
           "user_sent": "Bu yaz Hopa'ya gidiyorum.",  --> correct sentence <--
           "ai_sent": "Bu yaz Hopa'ya gidiyorum.",
           "ai_explanation": "The sentence uses the correct grammar."
           }, 
           {
           "id": "2",
           "grammar_point": "geniş zaman (-ir/-er)",
           "eng_grammar_point": "simple present tense",
           "user_sent": "Biz her yillar biz Fethiye'ye giderim.",  --> incorrect sentence <--
           "ai_sent": "Biz her yillar biz Fethiye'ye giderim.",
           "ai_explanation": "The word 'yillar' should be 'yıl' and the verb ending must match 'biz' (we)."
           }
         ]
     }  
   }
}


Delete a Challenge / Users/ChallengesController#destroy

DELETE "/api/v1/users/:user_id/challenges/:id"

Response:
Status: 204

Error Object

example: GET "/api/v1/users/:user_id/challenges/:invalid_id"

Response:
Status: 400
{
  "errors": [
    {
      "status": "400",
      "title": "Invalid Request",
      "detail": "Couldn't find Challenge with 'id'=<id>"
    }
  ]
}