{"id":15393142,"url":"https://github.com/shgysk8zer0/api-specs","last_synced_at":"2026-01-20T05:01:17.244Z","repository":{"id":79780694,"uuid":"99949522","full_name":"shgysk8zer0/api-specs","owner":"shgysk8zer0","description":"Specifications for the microdata API (unnamed)","archived":false,"fork":false,"pushed_at":"2017-08-16T20:29:55.000Z","size":12,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-12T21:45:52.639Z","etag":null,"topics":["api","html","html5","json","json-api","json-ld","microdata","rest","schema","schema-org","spec","specification","template"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shgysk8zer0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-10T17:38:47.000Z","updated_at":"2017-08-15T22:20:23.000Z","dependencies_parsed_at":"2023-02-26T18:31:34.554Z","dependency_job_id":null,"html_url":"https://github.com/shgysk8zer0/api-specs","commit_stats":{"total_commits":6,"total_committers":2,"mean_commits":3.0,"dds":"0.16666666666666663","last_synced_commit":"1f7372a5a75e78e185d0ef503fd8d74420e33702"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shgysk8zer0%2Fapi-specs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shgysk8zer0%2Fapi-specs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shgysk8zer0%2Fapi-specs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shgysk8zer0%2Fapi-specs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shgysk8zer0","download_url":"https://codeload.github.com/shgysk8zer0/api-specs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247508891,"owners_count":20950230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","html","html5","json","json-api","json-ld","microdata","rest","schema","schema-org","spec","specification","template"],"created_at":"2024-10-01T15:18:00.633Z","updated_at":"2026-01-20T05:01:12.218Z","avatar_url":"https://github.com/shgysk8zer0.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# api-specs\nSpecifications for the microdata API (unnamed)\n\n## Index\n- [Overview](#overview)\n- [Relevant Resources](#relevant-resources)\n- [Request structure](#request-structure)\n- [Examples](#examples)\n- [Advanced Examples](#advanced-example)\n- [Submitting Complex Objects](#submitting-complex-objects)\n- [Collections and Lists](#collections-and-lists)\n- [Contributing](./docs/CONTRIBUTING.md)\n\n## Overview\n\u003e Most websites and apps are, at their core, displaying variable content inside\n\u003e of templates. Social networking sites have posts (*perhaps with photos or videos*),\n\u003e which may have some comments. E-commerce sites have products with photos and\n\u003e descriptions, along with reviews. News sites have articles written by authors,\n\u003e again with comments. You might also see information about people, organizations,\n\u003e places and events. Ultimately, the web is full of information about things, with\n\u003e content placed within templates.\n\n\u003e Numerous APIs and templating languages have been created to address this, but\n\u003e developers are then required to learn multiple APIs with different structures\n\u003e and methods, different templating languages, etc. There is no standard. APIs\n\u003e cannot share resources and context. In other words, existing APIs are essentially\n\u003e proprietary and of limited usefulness.\n\n\u003e Google, Microsoft, Yahoo and Yandex founded [schema.org](https://schema.org) in\n\u003e an attempt to provide search engines better understanding of pages through\n\u003e `itemtype` and `itemprop` attributes in HTML, but they also extended JSON into\n\u003e something called JSON-LD, as a pure data representation. Combining this\n\u003e relation between data and `\u003ctempalte\u003e`s (*possibly loaded via `\u003clink rel=\"import\"/\u003e`*),\n\u003e and providing a REST API for managing data would allow developers to create and\n\u003e maintain applications simply by creating templates with the appropriate content\n\u003e and attributes, and filling them in with data obtainable through a simple `GET`\n\u003e request. Creating data can be created through a simple `POST`. Objects/properties\n\u003e directly map from `\u003cinput\u003e`s, to database fields, to properties of an AJAX request,\n\u003e to templates in HTML (*and are well documented*).\n\n\u003e This would, not only make creating apps much easier, but it would also\n\u003e allow for creating complex content that is very descriptive and also defines\n\u003e the relation between different representations of data.\n\n**This is a non-code repository for describing the structure and functionality\nof the API, as well as how mapping data to content will take place.**\n\n## Relevant Resources\n- [Schema.org](https://schema.org)\n- [`\u003ctemplate\u003e`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template)\n- [Full schema list](https://schema.org/docs/full.html)\n- [HTML Imports](https://www.html5rocks.com/en/tutorials/webcomponents/imports/)\n\n## Request Structure\nUses typical REST methods with endpoints mirroring vocabulary and schema defined\non [schema.org](https://schema.org/docs/full.html)\n\n- `GET /Person/dc67d265e8b544b62f8fea85083fde45` Get an individual entry\n- `GET /Person/dc67d265e8b544b62f8fea85083fde45?fields=givenName,familyName`\nRestrict response data\n- `GET /Person/?familyName=Smith\u0026limit=15\u0026offset=16` Get a list of 15 entries with the last\nname, \"Smith\", starting with the 16th entry (for pagination)\n- `POST /Person/` Create a new entry. Responds with hash id\n(requires form data or JSON)\n- `PUT /Person/dc67d265e8b544b62f8fea85083fde45` Update an entry\n(requires form data or JSON)\n- `DELETE /Person/dc67d265e8b544b62f8fea85083fde45` Delete an entry\n- `HEAD /ImageObject/ca29845ff732289185379d697b8d4b86` Get meta data (might useful for ImageObjects, etc.)\n\n## Examples\n\n- [Full documentation](https://schema.org/Person)\n- Response to be given\n```json\n{\n    \"@type\": \"Person\",\n    \"@context\": \"http://schema.org\",\n    \"givenName\": \"Chris\",\n    \"familyName\": \"Zuber\"\n}\n```\n\n- Basic HTML with template\n```html\n\u003cscript src=\"//cdn.domain.tld/js/schema.js\"\u003e\u003c/script\u003e\n\u003c!--\n    `data-import` specifies both a data source, as well as a template to use for\n    the returned data through use of the URL's hash.\n\n    Note that the URL structure of the REST API mimics that of schema.org's definitions.\n--\u003e\n\u003cdiv data-import=\"//api.domain.tld/Person/dc67d265e8b544b62f8fea85083fde45#person-template\"\u003e\u003c/div\u003e\n\u003ctemplate id=\"person-template\"\u003e\n    \u003cdiv itemtype=\"http://schema.org/Person\"\u003e\n        \u003cspan itemprop=\"givenName\"\u003e\u003c/span\u003e\n        \u003cspan itemprop=\"familyName\"\u003e\u003c/span\u003e\n        \u003c!-- ... --\u003e\n    \u003c/div\u003e\n\u003c/person\u003e\n```\n\n- HTML using [`\u003clink rel=\"import\"\u003e`](https://www.html5rocks.com/en/tutorials/webcomponents/imports/)\n```html\n\u003cscript src=\"//cdn.domain.tld/js/schema.js\"\u003e\u003c/script\u003e\n\u003c!-- Loads template as seen in above example --\u003e\n\u003clink rel=\"import\" href=\"//cdn.domain.tld/templates/person.html\" name=\"person-template\" /\u003e\n\u003cdiv data-import=\"//api.domain.tld/Person/dc67d265e8b544b62f8fea85083fde45#person-template\"\u003e\u003c/div\u003e\n```\n\n- Creating content\n```html\n\u003cform action=\"//api.domain.tld/Person\" method=\"POST\"\u003e\n    \u003cinput type=\"text\" name=\"givenName\" placeholder=\"First Name\" required=\"\" /\u003e\n    \u003cbr /\u003e\n    \u003cinput type=\"text\" name=\"familyName\" placeholder=\"Last Name\" required=\"\" /\u003e\n    \u003c!-- ... --\u003e\n\u003c/form\u003e\n```\n\n## Advanced Example\n\n```json\n{\n    \"@type\": \"Article\",\n    \"@context\": \"http://schema.org\",\n    \"headline\": \"Lorem Ipsum\",\n    \"description\": \"...\",\n    \"keywords\": \"a, b, ...\",\n    \"articleBody\": \"Laboriosam in molestiae consequatur maxime.\",\n    \"wordCount\": 1378,\n    \"dateCreated\": \"2017-08-12T14:32:01\",\n    \"thumbnailUrl\": \"https://cdn.domain.tld/img/ipsum.jpg\",\n    \"license\": \"http://creativecommons.org/licenses/by-sa/4.0/\",\n    \"author\": {\n        \"@type\": \"Person\",\n        \"givenName\": \"John\",\n        \"familyName\": \"Smith\",\n        \"image\": {\n            \"@type\": \"ImageObject\",\n            \"url\": \"https://cdn.domain.tld/img/JohnSmith.jpg\",\n            \"width\": 128,\n            \"height\": 128\n        }\n    },\n    \"publisher\": {\n        \"@type\": \"Organization\",\n        \"name\": \"ACME Inc.\",\n        \"address\": {},\n        \"logo\": {},\n        \"url\": \"http://www.acme.org\"\n    },\n    \"commentCount\": 1,\n    \"comment\": [{\n        \"@type\": \"Comment\",\n        \"upvoteCount\": 7,\n        \"downcoteCount\": 3,\n        \"author\": {},\n        \"dateCreated\": \"2017-08-14T16:04:00\",\n        \"text\": \"...\"\n    }]\n}\n```\n\n```html\n\u003c!--\n    Note that there can be more than one template for an itemtype, which is why\n    the \"data-template\" attribute is necessary. Also, it is up to the template\n    to determine which template to use for any properties in data that are,\n    themselves, objects.\n\n    You will also notice that values are not always intended to be used as node\n    values. Sometimes, they are the URL for links. Other times, they need to be\n    represented as both content and attribute, such as for `\u003ctime datetime=\"\"\u003e\u003c/time\u003e`.\n    In such cases, additional attributes using dataset may be necessary in order\n    to have the same data formatted in different ways.\n--\u003e\n\u003ctemplate id=\"article-template\"\u003e\n    \u003carticle itemtype=\"http://schema.org/Article\"\u003e\n        \u003cmeta itemprop=\"wordCount\" content=\"\" /\u003e\n        \u003cheader\u003e\n            \u003ch1 itemprop=\"headline\"\u003e\u003c/h1\u003e\n            By \u003cdiv itemprop=\"author\" itemtype=\"http://schema.org/Person\" data-template=\"#author-template\"\u003e\u003c/div\u003e\n            on \u003ctime datetime=\"\" itemprop=\"datePublished\" data-date-format=\"Y-m-d\"\u003e\u003c/time\u003e\n        \u003c/header\u003e\n        \u003c!-- Will be cloned for each section of article --\u003e\n        \u003csection itemprop=\"articleSection\"\u003e\u003c/section\u003e\n        \u003cfooter\u003e\n            \u003cdiv itemprop=\"comment\" data-tempalte=\"comment-tempalte\"\u003e\u003c/div\u003e\n        \u003c/footer\u003e\n    \u003c/article\u003e\n\u003c/tempalte\u003e\n\u003ctempalte id=\"author-tempalte\"\u003e\n    \u003cdiv itemtype=\"http://schema.org/Person\"\u003e\n        \u003cimg src=\"\" itemprop=\"image\" class=\"round shadow author-img\" /\u003e\n        \u003cspan itemprop=\"givenName\"\u003e\u003c/span\u003e\n        \u003cspan itemprop=\"familyName\"\u003e\u003c/span\u003e\n        \u003c!-- \"sameAs\" is often used for social links --\u003e\n        \u003ca href=\"\" itemprop=\"sameAs\"\u003e\n            \u003csvg width=\"32\" height=\"32\"\u003e\u003cuse xlink:href=\"//cdn.domain.tld/img/icons.svg#twitter\" /\u003e\u003c/svg\u003e\n        \u003c/a\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n\u003ctemplate id=\"comment-tempalte\"\u003e\n    \u003cdiv itemtype=\"http://schema.org/Comment\"\u003e\n        By \u003cspan itemprop=\"author\" data-tempalte=\"person-tempalte\"\u003e\u003c/span\u003e\n        On \u003ctime datetime=\"\" itemprop=\"dateCreated\"\u003e\u003c/time\u003e\n        \u003cblockquote itemprop=\"text\"\u003e\u003c/blockquote\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n```\n\n## Submitting Complex Objects\n\nSubmitting data will typically involve properties which are, themselves, objects.\nIt is also likely that a particular property may have multiple valid types that\nit would accept (i.e. [Person](https://schema.org/Person)/homeLocation).\n\nFor this reason, structuring forms such that the data they submit is similar in\nstructure to the JSON-LD representaion is necessary.\n\n```html\n\u003cform action=\"/Person\" method=\"POST\"\u003e\n    \u003cfieldset\u003e\n        \u003clegend\u003eName\u003c/legend\u003e\n        \u003c!-- Typical, simple data width @type \u0026 @context as hidden inputs --\u003e\n        \u003cinput type=\"hidden\" name=\"@type\" value=\"Person\" /\u003e\n        \u003cinput type=\"hidden\" name=\"@context\" value=\"http://schema.org\" /\u003e\n        \u003cinput type=\"text\" name=\"givenName\" required /\u003e\n        \u003cinput type=\"text\" name=\"familyName\" /\u003e\n    \u003c/fieldset\u003e\n    \u003cfieldset\u003e\n        \u003clegend\u003eHome Address\u003c/legend\u003e\n        \u003cinput type=\"hidden\" name=\"address[@type]\" value=\"PostalAddress\" /\u003e\n        \u003cinput type=\"text\" name=\"address[streetAddress]\" /\u003e\n        \u003c!-- ... Address Data ... --\u003e\n    \u003c/fieldset\u003e\n    \u003c!-- Multiple values --\u003e\n    \u003cinput type=\"url\" name=\"sameAs[]\" placeholder=\"Twitter URL\" /\u003e\n    \u003cbr /\u003e\n    \u003cinput type=\"url\" name=\"sameAs[]\" placeholder=\"GitHub profile URL\" /\u003e\n    \u003c!-- Multiple values of varying types --\u003e\n    \u003cinput type=\"url\" name=\"image[]\" placeholder=\"Gravatar URL\" /\u003e\n    \u003cfieldset\u003e\n        \u003c!-- Need to determine handling of uploads, but good example --\u003e\n        \u003cinput type=\"hidden\" name=\"image[][@type]\" value=\"ImageObject\" /\u003e\n        \u003cinput type=\"file\" name=\"image[][$file?]\" /\u003e\n        \u003ctextarea name=\"image[][caption]\"\u003e\u003c/textarea\u003e\n        \u003c!-- ... --\u003e\n    \u003c/fieldset\u003e\n    \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n\u003c/form\u003e\n```\n\n## Collections and Lists\n\nAny `GET` request to a resouce type [`GET /{Thing}`] without an identifier **MUST**\nreturn an [`ItemList`](https://schema.org/ItemList) containing an array of\n[`ListItem`s](https://schema.org/ListItem). Pagination is strongly encouraged.\n\n### Requests\n\n- `GET /{:Thing}[?[{(name|id|...)=:query}+][\u0026limit=:limit][\u0026offset=:offset]]`\n- `GET /SoftwareApplication`\n- `GET /Person?givenName=Smith\u0026limit=10\u0026offset=20`\n\n### Example Response\n\n```json\n{\n    \"@type\": \"ItemList\",\n    \"@context\": \"http://schema.org\",\n    \"numberOfItems\": 2,\n    \"itemListOrder\": \"Ascending\",\n    \"itemListElement\": [\n        {\n            \"@type\": \"ListItem\",\n            \"item\": {\n                \"@type\": \"Thing\",\n                \"name\": \"Thing 1\",\n                \"url\": \"https://api.domain.tld/Thing/?item=1\"\n            },\n            \"position\": 1,\n            \"nextItem\": \"https://api.domain.tld/Thing/?item=2\"\n        },\n        {\n            \"@type\": \"ListItem\",\n            \"item\": {\n                \"@type\": \"Thing\",\n                \"name\": \"Thing 2\",\n                \"url\": \"https://api.domain.tld/Thing/?item=2\"\n            },\n            \"position\": 2,\n            \"previousItem\": \"https://api.domain.tld/Thing/?item=1\"\n        }\n    ]\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshgysk8zer0%2Fapi-specs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshgysk8zer0%2Fapi-specs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshgysk8zer0%2Fapi-specs/lists"}