Skip to content

Instantly share code, notes, and snippets.

@mattrayner

mattrayner/README.md

Last active October 6, 2021 12:44
Show Gist options
  • Save mattrayner/322251d129339a16b967 to your computer and use it in GitHub Desktop.
Save mattrayner/322251d129339a16b967 to your computer and use it in GitHub Desktop.
Download ZIP
API Example
Raw
README.md

Example JSON API

This example JSON responds in accordance with the JSON API 1.0 specification

Endpoints

Available endpoints:

/v1/tokens

GET /v1/tokens/:id

Based on the :id value passed to the token endpoint you will receive 1 of 3 results, people, books or an error.

people
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/tokens/04b42572373080/",
    "related": "http://example.com/v1/people/1/"
  },
  "data": {
    "type": "people",
    "id": "1",
    "attributes": {
      "firstname": "Matt",
      "lastname": "Rayner",
      "email": "matthew.rayner@example.com"
    }
  },
  "relationships": {
    "checked_out_books": {
      "data": [
        {
          "type": "books",
          "id": "1"
        },
        {
          "type": "books",
          "id": "2"
        }
      ]
    },
    "tokens": {
      "data": [
        {
          "type": "tokens",
          "id": "04b42572373080"
        }
      ]
    }
  },
  "included": [
    {
      "type": "books",
      "id": "1",
      "attributes": {
        "title": "The Will-grounded Rubyist",
        "author": "David A. Black",
        "year": "2009",
        "thumbnail": "http://books.google.co.uk/books/content?id=igPTngEACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
        "isbn": "1617291692",
        "google_books_id": "igPTngEACAAJ"
      },
      "links": {
        "self": "http://example.com/v1/books/1/"
      }
    },
    {
      "type": "books",
      "id": "2",
      "attributes": {
        "title": "The Ruby Way",
        "author": "Hal Fulton",
        "year": "2002",
        "thumbnail": "http://books.google.co.uk/books/content?id=ows9jTsyaaEC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
        "isbn": "0672320835",
        "google_books_id": "ows9jTsyaaEC"
      },
      "links": {
        "self": "http://example.com/v1/books/2/"
      }
    },
    {
      "type": "tokens",
      "id": "04b42572373080",
      "attributes": {
        "type": "people",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04b42572373080/"
      }
    }
  ]
}
books
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/tokens/04a42572373080/",
    "related": "http://example.com/v1/books/1/"
  },
  "data": {
    "type": "books",
    "id": "1",
    "attributes": {
      "title": "The Will-grounded Rubyist",
      "author": "David A. Black",
      "year": "2009",
      "thumbnail": "http://books.google.co.uk/books/content?id=igPTngEACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
      "isbn": "1617291692",
      "google_books_id": "igPTngEACAAJ"
    }
  },
  "relationships": {
    "checked_out_by": {
      "data": [
        {
          "type": "people",
          "id": "1"
        }
      ]
    },
    "tokens": {
      "data": [
        {
          "type": "tokens",
          "id": "04a42572373080"
        },
        {
          "type": "tokens",
          "id": "04d42572373080"
        }
      ]
    }
  },
  "included": [
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "firstname": "Matt",
        "lastname": "Rayner",
        "email": "matthew.rayner@example.com"
      },
      "links": {
        "self": "http://example.com/v1/people/1/"
      }
    },
    {
      "type": "tokens",
      "id": "04a42572373080",
      "attributes": {
       "type": "books",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04a42572373080/"
      }
    },
    {
      "type": "tokens",
      "id": "04d42572373080",
      "attributes": {
        "type": "books",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04d42572373080/"
      }
    }
  ]
}
invalid
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/tokens/1234/"
  },
  "errors": [
    {
      "status": "404",
      "title": "Token not found",
      "details": "The token passed could not be found",
      "code": "404-T"
    }
  ]
}

/v1/checkouts

POST /v1/checkouts

This POST endpoint takes the following data:

{
  "book_token_id": "04a42572373080",
  "person_token_id": "04b42572373080"
}

And will respond with 1 of 2 responses:

valid
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/checkouts/"
  },
  "data": {
    "type": "checkouts",
    "id": "1",
    "attributes": {
      "book_token_id": "04a42572373080",
      "person_token_id": "04b42572373080",
      "returned_at": null,
      "created_at": "2016-03-14 17:32:16"
    }
  },
  "relationships": {
    "tokens": {
      "data": [
        {
          "type": "tokens",
          "id": "04a42572373080"
        },
        {
          "type": "tokens",
          "id": "04b42572373080"
        }
      ]
    },
    "books": {
      "data": [
        {
          "type": "books",
          "id": "1"
        }
      ]
    },
    "people": {
      "data": [
        {
          "type": "people",
          "id": "1"
        }
      ]
    }
  },
  "included": [
    {
      "type": "tokens",
      "id": "04a42572373080",
      "attributes": {
        "type": "books",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04a42572373080/"
      }
    },
    {
      "type": "tokens",
      "id": "04b42572373080",
      "attributes": {
        "type": "people",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04b42572373080/"
      }
    },
    {
      "type": "books",
      "id": "1",
      "attributes": {
        "title": "The Will-grounded Rubyist",
        "author": "David A. Black",
        "year": "2009",
        "thumbnail": "http://books.google.co.uk/books/content?id=igPTngEACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
        "isbn": "1617291692",
        "google_books_id": "igPTngEACAAJ"
      },
      "links": {
        "self": "http://example.com/v1/books/1/"
      }
    },
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "firstname": "Matt",
        "lastname": "Rayner",
        "email": "matthew.rayner@example.com"
      },
      "links": {
        "self": "http://example.com/v1/people/1/"
      }
    }
  ]
}
invalid
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/checkouts/"
  },
  "errors": [
    {
      "status": "404",
      "title": "Book not found",
      "details": "The book passed could not be found",
      "code": "404-B"
    },
    {
      "status": "404",
      "title": "Person not found",
      "details": "The person passed could not be found",
      "code": "404-P"
    },
    {
      "status": "400",
      "title": "Book already checked-out",
      "details": "The book passed has already been checked out",
      "code": "401-CO"
    }
  ]
}

/v1/returns

POST /v1/returns

This POST endpoint takes the following data:

{
  "book_token_id": "04a42572373080"
}

and will respond with 1 of 2 results:

valid
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/returns/"
  },
  "data": {
    "type": "checkouts",
    "id": "1",
    "attributes": {
      "book_token_id": "04a42572373080",
      "person_token_id": "04b42572373080",
      "returned_at": "2016-03-14 18:58:53",
      "created_at": "2016-03-14 17:32:16"
    }
  },
  "relationships": {
    "tokens": {
      "data": [
        {
          "type": "tokens",
          "id": "04a42572373080"
        },
        {
          "type": "tokens",
          "id": "04b42572373080"
        }
      ]
    },
    "books": {
      "data": [
        {
          "type": "books",
          "id": "1"
        }
      ]
    },
    "people": {
      "data": [
        {
          "type": "people",
          "id": "1"
        }
      ]
    }
  },
  "included": [
    {
      "type": "tokens",
      "id": "04a42572373080",
      "attributes": {
        "type": "books",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04a42572373080/"
      }
    },
    {
      "type": "tokens",
      "id": "04b42572373080",
      "attributes": {
        "type": "people",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04b42572373080/"
      }
    },
    {
      "type": "books",
      "id": "1",
      "attributes": {
        "title": "The Will-grounded Rubyist",
        "author": "David A. Black",
        "year": "2009",
        "thumbnail": "http://books.google.co.uk/books/content?id=igPTngEACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
        "isbn": "1617291692",
        "google_books_id": "igPTngEACAAJ"
      },
      "links": {
        "self": "http://example.com/v1/books/1/"
      }
    },
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "firstname": "Matt",
        "lastname": "Rayner",
        "email": "matthew.rayner@example.com"
      },
      "links": {
        "self": "http://example.com/v1/people/1/"
      }
    }
  ]
}
invalid
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/returns/"
  },
  "errors": [
    {
      "status": "404",
      "title": "Book not found",
      "details": "The book passed could not be found",
      "code": "404-B"
    },
    {
      "status": "400",
      "title": "Book already returned",
      "details": "The book passed has already been checked out",
      "code": "400-RA"
    },
    {
      "status": "400",
      "title": "Book not checked-out",
      "details": "The book passed is not checked-out",
      "code": "400-RN"
    }
  ]
}

/v1/books

This endpoint takes the following data:

{
  "title": "The Will-grounded Rubyist",
  "author": "David A. Black",
  "year": "2009",
  "thumbnail": "http://books.google.co.uk/books/content?id=igPTngEACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
  "isbn": "1617291692",
  "google_books_id": "igPTngEACAAJ"
}

NOTE: title, author and year are the only required attributes

POST /v1/books

valid
invalid

PATCH/PUT /v1/books/:id

valid
invalid

GET /v1/books/:id

valid
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://example.com/v1/books/1/"
  },
  "data": {
    "type": "books",
    "id": "1",
    "attributes": {
      "title": "The Will-grounded Rubyist",
      "author": "David A. Black",
      "year": "2009",
      "thumbnail": "http://books.google.co.uk/books/content?id=igPTngEACAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api",
      "isbn": "1617291692",
      "google_books_id": "igPTngEACAAJ"
    }
  },
  "relationships": {
    "checked_out_by": {
      "data": [
        {
          "type": "people",
          "id": "1"
        }
      ]
    },
    "tokens": {
      "data": [
        {
          "type": "tokens",
          "id": "04a42572373080"
        },
        {
          "type": "tokens",
          "id": "04d42572373080"
        }
      ]
    }
  },
  "included": [
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "firstname": "Matt",
        "lastname": "Rayner",
        "email": "matthew.rayner@example.com"
      },
      "links": {
        "self": "http://example.com/v1/people/1/"
      }
    },
    {
      "type": "tokens",
      "id": "04a42572373080",
      "attributes": {
        "type": "books",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04a42572373080/"
      }
    },
    {
      "type": "tokens",
      "id": "04d42572373080",
      "attributes": {
        "type": "books",
        "foreign_key": "1"
      },
      "links": {
        "self": "http://example.com/v1/tokens/04d42572373080/"
      }
    }
  ]
}
invalid

/v1/people

This endpoint takes the following data:

{
  "firstname": "Matt",
  "lastname": "Rayner",
  "email": "matthew.rayner@example.com"
}

POST /v1/people

valid
invalid

PATCH/PUT /v1/people/:id

valid
invalid

GET /v1/people/:id

valid
invalid
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment