Contractor Skill API Doc

pages/api.yml

@@ -66,6 +66,10 @@ endpoint_sections:
     title: Contractors (Tutors)
     id: contractors
     layout: /contractors/contractors.yml
+  -
+    title: Contractor Skills
+    id: contractor-skills
+    layout: /contractor-skills/contractor-skills.yml
   -
     title: Countries
     id: countries

pages/contractor-skills/contractor-skills-object.json

@@ -0,0 +1,23 @@
+{
+  "id": 2,
+  "contractor": {
+    "id": 52,
+    "first_name": "James",
+    "last_name": "Higgins",
+    "email": "[email protected]",
+    "url": "http://localhost:8000/api/contractors/52/"
+  },
+  "subject": {
+    "id": 159,
+    "name": "PGCE",
+    "category_id": 15,
+    "category_name": "Teaching Skill",
+    "custom_to_branch": null
+  },
+  "qual_level": {
+    "id": 14,
+    "name": "BA",
+    "ranking": 50.0,
+    "custom_to_branch": null
+  }
+}

pages/contractor-skills/contractor-skills-object.md

@@ -0,0 +1,5 @@
+### Contractor Skills Object
+
+A Contractor Skills object represents the relationship between a Contractor and a Skill. A Skill is defined by a combination of a [Subject](#subjects) and a [Qualification Level](#qual-level). For example, a Skill might be "Mathematics (A Level)" where "Mathematics" is the Subject and "A Level" is the Qualification Level.
+
+When you retrieve a Contractor Skill, you'll get the full details of the Contractor, along with the associated Subject and Qualification Level information. This allows you to see not just which skills a Contractor has, but also the specific Qualification Levels for each subject they can teach. 

pages/contractor-skills/contractor-skills-object.yml

@@ -0,0 +1,76 @@
+attributes:
+  -
+    name: id
+    type: integer
+    description: Unique identifier for the contractor skill object.
+  -
+    name: contractor
+    type: object
+    description: The contractor this skill is associated with.
+    children:
+      -
+        name: id
+        type: integer
+        description: Unique identifier for the contractor.
+      -
+        name: first_name
+        type: string
+        description: The contractor's first name.
+      -
+        name: last_name
+        type: string
+        description: The contractor's last name.
+      -
+        name: email
+        type: string
+        description: The contractor's email address.
+      -
+        name: url
+        type: string
+        description: API URL for the full contractor details.
+  -
+    name: subject
+    type: object
+    description: The subject details.
+    children:
+      -
+        name: id
+        type: integer
+        description: Unique identifier for the subject.
+      -
+        name: name
+        type: string
+        description: Name of the subject.
+      -
+        name: category_id
+        type: integer
+        description: ID of the subject category.
+      -
+        name: category_name
+        type: string
+        description: Name of the subject category.
+      -
+        name: custom_to_branch
+        type: bool
+        description: Indicates whether the Subject is custom to the API key's Branch (True), or shared across all Branches (null).
+  -
+    name: qual_level
+    type: object
+    description: The qualification level details.
+    children:
+      -
+        name: id
+        type: integer
+        description: Unique identifier for the qualification level.
+      -
+        name: name
+        type: string
+        description: Name of the qualification level.
+      -
+        name: ranking
+        type: decimal
+        description: Numerical ranking of the qualification level.
+      -
+        name: custom_to_branch
+        type: bool
+        description: Indicates whether the Qualification Level is custom to the API key's Branch (True), or shared across all Branches (null).

pages/contractor-skills/contractor-skills.yml

@@ -0,0 +1,39 @@
+sections:
+  -
+    title: Contractor Skills Object
+    id: contractor-skills-object
+    description: /contractor-skills/contractor-skills-object.md
+    attributes: /contractor-skills/contractor-skills-object.yml
+    response: /contractor-skills/contractor-skills-object.json
+    response_title: OBJECT
+  -
+    title: List all Contractor Skills
+    id: list-all-contractor-skills
+    description: /contractor-skills/list-all-contractor-skills.md
+    code: /contractor-skills/list-all-contractor-skills.py
+    code_type: GET
+    code_url: /api/contractor-skills/
+    response: /contractor-skills/list-all-contractor-skills.json
+  -
+    title: Get a Contractor Skill
+    id: get-a-contractor-skill
+    description: /contractor-skills/get-a-contractor-skill.md
+    code: /contractor-skills/get-a-contractor-skill.py
+    code_type: GET
+    code_url: /api/contractor-skills/<id>/
+    response: /contractor-skills/get-a-contractor-skill.json
+  -
+    title: Create a Contractor Skill
+    id: create-a-contractor-skills
+    description: /contractor-skills/create-a-contractor-skill.md
+    code: /contractor-skills/create-a-contractor-skill.py
+    code_type: POST
+    code_url: /api/contractor-skills/
+    response: /contractor-skills/create-a-contractor-skill.json
+  -
+    title: Delete a Contractor Skill
+    id: delete-a-contractor-skill
+    description: /contractor-skills/delete-a-contractor-skill.md
+    code: /contractor-skills/delete-a-contractor-skill.py
+    code_type: DELETE
+    code_url: /api/contractor-skills/<id>/

pages/contractor-skills/create-a-contractor-skill.json

@@ -0,0 +1,23 @@
+{
+    "id": 135,
+    "contractor": {
+        "id": 69,
+        "first_name": "Billy",
+        "last_name": "Holiday",
+        "email": null,
+        "url": "http://localhost:8000/api/contractors/69/"
+    },
+    "subject": {
+        "id": 51,
+        "name": "Religious Studies",
+        "category_id": 8,
+        "category_name": "Humanities",
+        "custom_to_branch": null
+    },
+    "qual_level": {
+        "id": 13,
+        "name": "Key Stage 5",
+        "ranking": 35.0,
+        "custom_to_branch": null
+    }
+}

pages/contractor-skills/create-a-contractor-skill.md

@@ -0,0 +1,3 @@
+### Add a Contractor Skill
+
+Creates a new Contractor Skill, representing a relationship between a Contractor and a combination of [Subject](#subjects) and [Qualification Level](#qual-levels). You need to provide the `contractor`, `subject`, and `qual_level` IDs in the request body. Subjects or Qualification Levels custom to another branch, hidden for the branch, or added specifically by the Contractor cannot be used. For more information about what “custom to branch” means, see [Subject](#subjects) and [Qualification Level](#qual-levels).

pages/contractor-skills/create-a-contractor-skill.py

@@ -0,0 +1,5 @@
+import pprint, requests
+data = {"contractor": 69,"subject": 51,"qual_level": 13}
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.post('https://secure.tutorcruncher.com/api/contractor-skills/',json=data, headers=headers)
+pprint.pprint(r.json())

pages/contractor-skills/delete-a-contractor-skill.md

@@ -0,0 +1,3 @@
+### Delete a Contractor Skill
+
+Deletes a Contractor Skill using its unique ID. Only Contractor Skills associated with the API key's Branch can be deleted. Attempts to delete a skill that belongs to a different Branch or references a Subject or Qualification Level hidden or restricted for the Branch will result in a `400 Bad Request` response. For more information about Branch-specific restrictions, see [Subject](#subjects) and [Qualification Level](#qual-levels).

pages/contractor-skills/delete-a-contractor-skill.py

@@ -0,0 +1,5 @@
+import pprint, requests
+
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.delete('https://secure.tutorcruncher.com/api/contractor-skills/1/', headers=headers)
+# Returns 204 on success 

pages/contractor-skills/get-a-contractor-skill.json

@@ -0,0 +1,23 @@
+{
+  "id": 2,
+  "contractor": {
+    "id": 52,
+    "first_name": "James",
+    "last_name": "Higgins",
+    "email": "[email protected]",
+    "url": "https://secure.tutorcruncher.com/api/contractors/52/"
+  },
+  "subject": {
+    "id": 159,
+    "name": "PGCE",
+    "category_id": 15,
+    "category_name": "Teaching Skill",
+    "custom_to_branch": null
+  },
+  "qual_level": {
+    "id": 14,
+    "name": "BA",
+    "ranking": 50.0,
+    "custom_to_branch": null
+  }
+} 

pages/contractor-skills/get-a-contractor-skill.md

@@ -0,0 +1,4 @@
+### Get a Contractor Skill
+
+Returns the details of an existing Contractor Skill. You only need to specify the unique `id` of the Contractor Skill to get the correct details.
+The response includes the full Contractor Skill object including the Contractor details, [Subject](#subjects) and [Qualification Level](#qual-level). 

pages/contractor-skills/get-a-contractor-skill.py

@@ -0,0 +1,5 @@
+import pprint, requests
+
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.get('https://secure.tutorcruncher.com/api/contractor-skills/2/', headers=headers)
+pprint.pprint(r.json()) 

pages/contractor-skills/list-all-contractor-skills.json

@@ -0,0 +1,30 @@
+{
+  "count": 2,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "id": 2,
+      "contractor": {
+        "id": 52,
+        "first_name": "James",
+        "last_name": "Higgins",
+        "email": "[email protected]",
+        "url": "https://secure.tutorcruncher.com/api/contractors/52/"
+      },
+      "subject": {
+        "id": 159,
+        "name": "PGCE",
+        "category_id": 15,
+        "category_name": "Teaching Skill",
+        "custom_to_branch": null
+      },
+      "qual_level": {
+        "id": 14,
+        "name": "BA",
+        "ranking": 50.0,
+        "custom_to_branch": null
+      }
+    }
+  ]
+} 

pages/contractor-skills/list-all-contractor-skills.md

@@ -0,0 +1,3 @@
+### List all Contractor Skills
+Returns a list of Contractor Skills, each representing a relationship between a Contractor and a combination of [Subject](#subjects) and [Qualification Level](#qual-levels). The results include only skills that are custom to the API key's Branch, exclude skills with hidden Subjects or Qualification Levels for the Branch, and include skills specifically added by the Contractor. If no skills match the filtering criteria, the response will return an empty results array. For more information about what "custom to branch" means, see [Subject](#subjects) and [Qualification Level](#qual-levels).
+

pages/contractor-skills/list-all-contractor-skills.py

@@ -0,0 +1,5 @@
+import pprint, requests
+
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.get('https://secure.tutorcruncher.com/api/contractor-skills/', headers=headers)
+pprint.pprint(r.json()) 

pages/contractors/contractor-object-v2.json

@@ -20,15 +20,51 @@
   "qualifications": [],
   "skills": [
     {
-      "id": 1436,
-      "subject": "American Studies",
-      "qual_level": "Key Stage 5"
-    },
+            "id": 145,
+            "contractor": {
+                "id": 568433,
+                "first_name": "James",
+                "last_name": "Higgins",
+                "email": "[email protected]",
+                "url": "https://secure.tutorcruncher.com/api/568433/"
+            },
+            "subject": {
+                "id": 98,
+                "name": "General Maths & Science",
+                "category_id": 11,
+                "category_name": "Other",
+                "custom_to_branch": null
+            },
+            "qual_level": {
+                "id": 3,
+                "name": "Common Entrance",
+                "ranking": 12.0,
+                "custom_to_branch": null
+            }
+        },
     {
-      "id": 4082,
-      "subject": "American Studies",
-      "qual_level": "A Level"
-    }
+            "id": 141,
+            "contractor": {
+                "id": 568433,
+                "first_name": "James",
+                "last_name": "Higgins",
+                "email": "[email protected]",
+                "url": "https://secure.tutorcruncher.com/api/568433/"
+            },
+            "subject": {
+                "id": 135,
+                "name": "Geology",
+                "category_id": 14,
+                "category_name": "Science",
+                "custom_to_branch": null
+            },
+            "qual_level": {
+                "id": 5,
+                "name": "GCSE",
+                "ranking": 14.0,
+                "custom_to_branch": null
+            }
+        }
   ],
   "institutions": [],
   "receive_service_notifications": true,