API Reference

JSON Schema REST API

API Versions

• v1

REST API Version v1

Resource endpoints

• POST - /api/v1/schemas
• GET - /api/v1/schemas
• GET - /api/v1/schemas/page
• GET - /api/v1/schemas/
• PUT - /api/v1/schemas
• DELETE - /api/v1/schemas/
• DELETE - /api/v1/schemas
• GET - /api/v1/schemas/search
• GET - /api/v1/schemas/versions
• POST - /api/v1/validate

Schema Resources

Create Schema

---

create json schema

• URL

  /api/v1/schemas

• Method:

  POST

• URL Params

  Required:

  None

• Data Params

  None

• Success Response:

  • Code: 201
    Content:

    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
      "title": "Sample title",
      "description": "Sample description",
      "type": "object",
      "meta": {},
      "properties": {}
    }

• Error Response:

  • Code: 400 BAD REQUEST
    Content:

    {
      "validationState": "INVALID",
      "validationJobId": null,
      "validationErrors": [
        {
          "ajvError": {
            "keyword": "required",
            "dataPath": ".meta",
            "schemaPath": "#/required",
            "params": {
              "missingProperty": "version"
            },
            "message": "should have required property 'version'"
          },
          "message": "should have required property 'version'",
          "absoluteDataPath": ".meta",
          "userFriendlyMessage": "should have required property 'version' at .meta"
        }
      ]
    }

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <JWT_TOKEN>" http://loclahost/api/v1/schemas \
   -d "{
          "$schema": "http://json-schema.org/draft-07/schema#",
          "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
          "title": "Sample title",
          "description": "Sample description",
          "type": "object",
          "meta": {},
          "properties": {}
        }"

Get Schemas

---

Getting all the schemas which have been stored

• URL

  /api/v1/schemas

• Method:

  GET

• URL Params

  Required:

  None

• Data Params

  None

• Success Response:

  • Code: 200
    Content:

    [    
        {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
          "title": "Sample title",
          "description": "Sample description",
          "type": "object",
          "meta": {},
          "properties": {}
        },
        {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
          "title": "Sample title",
          "description": "Sample description",
          "type": "object",
          "meta": {},
          "properties": {}
        },
        ...
    ]

• Error Response:

  • Code: 500 Internal Server Error
    Content: NONE

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X GET -H "Authorization: Bearer <JWT_TOKEN>" http://loclahost/api/v1/schemas

Get Schema + pagination

---

Getting a schema as a page object

• URL

  /api/v1/schemas/page

• Method:

  GET

• URL Params

  Required:

  None

• Data Params

  page=[integer] size=[integer]

• Success Response:

  • Code: 200
    Content:

        {
          "content": [
            {
              "$schema": "http://json-schema.org/draft-07/schema#",
              "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
              "title": "Sample title",
              "description": "Sample description",
              "type": "object",
              "meta": {},
              "properties": {}
            }
          ],
          "pageable": {
            "sort": {
              "unsorted": true,
              "sorted": false,
              "empty": true
            },
            "offset": 0,
            "pageNumber": 0,
            "pageSize": 3,
            "paged": true,
            "unpaged": false
          },
          "totalPages": 5,
          "totalElements": 13,
          "last": false,
          "size": 3,
          "number": 0,
          "sort": {
            "unsorted": true,
            "sorted": false,
            "empty": true
          },
          "first": true,
          "numberOfElements": 3,
          "empty": false
        }

• Error Response:

  • Code: 500 Internal Server Error
    Content: NONE

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X GET -H "Authorization: Bearer <JWT_TOKEN>" http://localhost:8080/api/v1/schemas/page?page=0&size=3

Get Schema By ID

---

Getting a schema by its id which have been stored

• URL

  /api/v1/schemas/

• Method:

  GET

• URL Params

  Required:

  None

• Data Params

  Required:

  id=[string]

• Success Response:

  • Code: 200
    Content:

        {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
          "title": "Sample title",
          "description": "Sample description",
          "type": "object",
          "meta": {},
          "properties": {}
        }

• Error Response:

  • Code: 500 Internal Server Error
    Content: NONE

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X GET -H "Authorization: Bearer <JWT_TOKEN>" http://loclahost/api/v1/schemas/?id=https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0

Update Schema

---

update a json schema

• URL

  /api/v1/schemas

• Method:

  PUT

• URL Params

  Required:

  None

• Data Params

  None

• Success Response:

  • Code: 201
    Content:

    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
      "title": "Sample title",
      "description": "Sample description",
      "type": "object",
      "meta": {},
      "properties": {}
    }

• Error Response:

  • Code: 400 BAD REQUEST
    Content:

    {
      "validationState": "INVALID",
      "validationJobId": null,
      "validationErrors": [
        {
          "ajvError": {
            "keyword": "required",
            "dataPath": ".meta",
            "schemaPath": "#/required",
            "params": {
              "missingProperty": "version"
            },
            "message": "should have required property 'version'"
          },
          "message": "should have required property 'version'",
          "absoluteDataPath": ".meta",
          "userFriendlyMessage": "should have required property 'version' at .meta"
        }
      ]
    }

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer <JWT_TOKEN>" http://loclahost/api/v1/schemas \
   -d "{
          "$schema": "http://json-schema.org/draft-07/schema#",
          "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
          "title": "Sample title",
          "description": "Sample description",
          "type": "object",
          "meta": {},
          "properties": {}
        }"

Delete Schema By ID

---

Removing a schema permanently by its ID

• URL

  /api/v1/schemas/

• Method:

  DELETE

• URL Params

  Required:

  None

• Data Params

  Required:

  id=[string]

• Success Response:

  • Code: 204 No Content
    Content: NONE

• Error Response:

  • Code: 500 Internal Server Error
    Content: NONE

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X DELETE -H "Authorization: Bearer <JWT_TOKEN>" http://loclahost/api/v1/schemas/?id=https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0

Delete Schema

---

Removing a schema permanently

• URL

  /api/v1/schemas

• Method:

  DELETE

• URL Params

  Required:

  None

• Data Params

  None

• Success Response:

  • Code: 204 No Content
    Content: NONE

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer <JWT_TOKEN>" http://loclahost/api/v1/schemas \
   -d "{"$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0"}"

Search Schemas

---

Search a schemas

• URL

  /api/v1/schemas/search

• Method:

  GET

• URL Params

  Required:

  None

• Data Params

  Required: key=[string]

  page=[integer] size=[integer]

• Success Response:

  • Code: 200
    Content:

        {
          "content": [
            {
              "$schema": "http://json-schema.org/draft-07/schema#",
              "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
              "title": "Sample title",
              "description": "Sample description",
              "type": "object",
              "meta": {},
              "properties": {}
            }
          ],
          "pageable": {
            "sort": {
              "unsorted": true,
              "sorted": false,
              "empty": true
            },
            "offset": 0,
            "pageNumber": 0,
            "pageSize": 3,
            "paged": true,
            "unpaged": false
          },
          "totalPages": 5,
          "totalElements": 13,
          "last": false,
          "size": 3,
          "number": 0,
          "sort": {
            "unsorted": true,
            "sorted": false,
            "empty": true
          },
          "first": true,
          "numberOfElements": 3,
          "empty": false
        }

• Error Response:

  • Code: 500 Internal Server Error
    Content: NONE

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X GET -H "Authorization: Bearer <JWT_TOKEN>" http://localhost:8080/api/v1/schemas/search?key=<SEARCH KEY VALUE>&page=0&size=20

Get list of versions of Schemas

---

Getting a list of versions of a schema by giving schema name.

• schemaName : id of a schema without version
  ex:- id : https://schemablocks.org/schemas/sb-phenopackets/Family/v1.103.0
  schemaName: https://schemablocks.org/schemas/sb-phenopackets/Family

• URL

  /api/v1/schemas/versions

• Method:

  GET

• URL Params

  Required:

  None

• Data Params

  Required: schemaName=[string]

  page=[integer] size=[integer]

• Success Response:

  • Code: 200
    Content:

        {
          "content": [
            {
              "$schema": "http://json-schema.org/draft-07/schema#",
              "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
              "title": "Sample title",
              "description": "Sample description",
              "type": "object",
              "meta": {},
              "properties": {}
            }
          ],
          "pageable": {
            "sort": {
              "unsorted": true,
              "sorted": false,
              "empty": true
            },
            "offset": 0,
            "pageNumber": 0,
            "pageSize": 3,
            "paged": true,
            "unpaged": false
          },
          "totalPages": 5,
          "totalElements": 13,
          "last": false,
          "size": 3,
          "number": 0,
          "sort": {
            "unsorted": true,
            "sorted": false,
            "empty": true
          },
          "first": true,
          "numberOfElements": 3,
          "empty": false
        }

• Error Response:

  • Code: 500 Internal Server Error
    Content: NONE

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X GET -H "Authorization: Bearer <JWT_TOKEN>" http://localhost:8080/api/v1/schemas/versions?schemaName=<SCHEMA NAME>&page=0&size=4

Meta Schema Resources

Get Meta Schema

---

Getting meta schemas which have been stored

• URL

  /api/v1/metaSchemas

• Method:

  GET

• URL Params

  Required:

  None

• Data Params

  None

• Success Response:

  • Code: 200
    Content:

    {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
          "title": "Sample title",
          "description": "Sample description",
          "type": "object",
          "meta": {},
          "properties": {}
    }

• Error Response:

  • Code: 500 Internal Server Error
    Content: NONE

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X GET -H "Authorization: Bearer <JWT_TOKEN>" http://localhost:8080/api/v1/metaSchemas

Schema Validation

Validate schema

---

get validation results of a schema

• URL

  /api/v1/validate

• Method:

  POST

• URL Params

  Required:

  None

• Data Params

  None

• Success Response:

  • Code: 200
    Content:

    {
      "validationState": "VALID",
      "validationJobId": null,
      "validationErrors": []
    }

• Error Response:

  • Code: 400 BAD REQUEST
    Content:

    {
      "validationState": "INVALID",
      "validationJobId": null,
      "validationErrors": [
        {
          "ajvError": {
            "keyword": "required",
            "dataPath": ".meta",
            "schemaPath": "#/required",
            "params": {
              "missingProperty": "version"
            },
            "message": "should have required property 'version'"
          },
          "message": "should have required property 'version'",
          "absoluteDataPath": ".meta",
          "userFriendlyMessage": "should have required property 'version' at .meta"
        }
      ]
    }

  OR

  • Code: 401 UNAUTHORIZED
    Content: { error : "You are unauthorized to make this request." }

• Sample Call:

    $ curl -i -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <JWT_TOKEN>" http://localhost:8080/api/v1/validate \
   -d "{
          "$schema": "http://json-schema.org/draft-07/schema#",
          "$id": "https://schemablocks.org/schemas/sb-phenopackets/Sample/v0.0.0",
          "title": "Sample title",
          "description": "Sample description",
          "type": "object",
          "meta": {},
          "properties": {}
        }"