Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/shgysk8zer0/api-specs

Specifications for the microdata API (unnamed)
https://github.com/shgysk8zer0/api-specs

api html html5 json json-api json-ld microdata rest schema schema-org spec specification template

Last synced: about 1 month ago
JSON representation

Specifications for the microdata API (unnamed)

Host: GitHub
URL: https://github.com/shgysk8zer0/api-specs
Owner: shgysk8zer0
Created: 2017-08-10T17:38:47.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2017-08-16T20:29:55.000Z (over 7 years ago)
Last Synced: 2024-11-01T12:11:54.412Z (3 months ago)
Topics: api, html, html5, json, json-api, json-ld, microdata, rest, schema, schema-org, spec, specification, template
Size: 11.7 KB
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 4
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md

Awesome Lists containing this project

README

# api-specs
Specifications for the microdata API (unnamed)

## Index
- [Overview](#overview)
- [Relevant Resources](#relevant-resources)
- [Request structure](#request-structure)
- [Examples](#examples)
- [Advanced Examples](#advanced-example)
- [Submitting Complex Objects](#submitting-complex-objects)
- [Collections and Lists](#collections-and-lists)
- [Contributing](./docs/CONTRIBUTING.md)

## Overview
> Most websites and apps are, at their core, displaying variable content inside
> of templates. Social networking sites have posts (*perhaps with photos or videos*),
> which may have some comments. E-commerce sites have products with photos and
> descriptions, along with reviews. News sites have articles written by authors,
> again with comments. You might also see information about people, organizations,
> places and events. Ultimately, the web is full of information about things, with
> content placed within templates.

> Numerous APIs and templating languages have been created to address this, but
> developers are then required to learn multiple APIs with different structures
> and methods, different templating languages, etc. There is no standard. APIs
> cannot share resources and context. In other words, existing APIs are essentially
> proprietary and of limited usefulness.

> Google, Microsoft, Yahoo and Yandex founded [schema.org](https://schema.org) in
> an attempt to provide search engines better understanding of pages through
> `itemtype` and `itemprop` attributes in HTML, but they also extended JSON into
> something called JSON-LD, as a pure data representation. Combining this
> relation between data and ``s (*possibly loaded via ``*),
> and providing a REST API for managing data would allow developers to create and
> maintain applications simply by creating templates with the appropriate content
> and attributes, and filling them in with data obtainable through a simple `GET`
> request. Creating data can be created through a simple `POST`. Objects/properties
> directly map from ``s, to database fields, to properties of an AJAX request,
> to templates in HTML (*and are well documented*).

> This would, not only make creating apps much easier, but it would also
> allow for creating complex content that is very descriptive and also defines
> the relation between different representations of data.

**This is a non-code repository for describing the structure and functionality
of the API, as well as how mapping data to content will take place.**

## Relevant Resources
- [Schema.org](https://schema.org)
- [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template)
- [Full schema list](https://schema.org/docs/full.html)
- [HTML Imports](https://www.html5rocks.com/en/tutorials/webcomponents/imports/)

## Request Structure
Uses typical REST methods with endpoints mirroring vocabulary and schema defined
on [schema.org](https://schema.org/docs/full.html)

- `GET /Person/dc67d265e8b544b62f8fea85083fde45` Get an individual entry
- `GET /Person/dc67d265e8b544b62f8fea85083fde45?fields=givenName,familyName`
Restrict response data
- `GET /Person/?familyName=Smith&limit=15&offset=16` Get a list of 15 entries with the last
name, "Smith", starting with the 16th entry (for pagination)
- `POST /Person/` Create a new entry. Responds with hash id
(requires form data or JSON)
- `PUT /Person/dc67d265e8b544b62f8fea85083fde45` Update an entry
(requires form data or JSON)
- `DELETE /Person/dc67d265e8b544b62f8fea85083fde45` Delete an entry
- `HEAD /ImageObject/ca29845ff732289185379d697b8d4b86` Get meta data (might useful for ImageObjects, etc.)

## Examples

- [Full documentation](https://schema.org/Person)
- Response to be given
```json
{
"@type": "Person",
"@context": "http://schema.org",
"givenName": "Chris",
"familyName": "Zuber"
}
```

- Basic HTML with template
```html

```

- HTML using [``](https://www.html5rocks.com/en/tutorials/webcomponents/imports/)
```html

```

- Creating content
```html

```

## Advanced Example

```json
{
"@type": "Article",
"@context": "http://schema.org",
"headline": "Lorem Ipsum",
"description": "...",
"keywords": "a, b, ...",
"articleBody": "Laboriosam in molestiae consequatur maxime.",
"wordCount": 1378,
"dateCreated": "2017-08-12T14:32:01",
"thumbnailUrl": "https://cdn.domain.tld/img/ipsum.jpg",
"license": "http://creativecommons.org/licenses/by-sa/4.0/",
"author": {
"@type": "Person",
"givenName": "John",
"familyName": "Smith",
"image": {
"@type": "ImageObject",
"url": "https://cdn.domain.tld/img/JohnSmith.jpg",
"width": 128,
"height": 128
}
},
"publisher": {
"@type": "Organization",
"name": "ACME Inc.",
"address": {},
"logo": {},
"url": "http://www.acme.org"
},
"commentCount": 1,
"comment": [{
"@type": "Comment",
"upvoteCount": 7,
"downcoteCount": 3,
"author": {},
"dateCreated": "2017-08-14T16:04:00",
"text": "..."
}]
}
```

```html

By
On

```

## Submitting Complex Objects

Submitting data will typically involve properties which are, themselves, objects.
It is also likely that a particular property may have multiple valid types that
it would accept (i.e. [Person](https://schema.org/Person)/homeLocation).

For this reason, structuring forms such that the data they submit is similar in
structure to the JSON-LD representaion is necessary.

```html

Name

Home Address

Submit

```

## Collections and Lists

Any `GET` request to a resouce type [`GET /{Thing}`] without an identifier **MUST**
return an [`ItemList`](https://schema.org/ItemList) containing an array of
[`ListItem`s](https://schema.org/ListItem). Pagination is strongly encouraged.

### Requests

- `GET /{:Thing}[?[{(name|id|...)=:query}+][&limit=:limit][&offset=:offset]]`
- `GET /SoftwareApplication`
- `GET /Person?givenName=Smith&limit=10&offset=20`

### Example Response

```json
{
"@type": "ItemList",
"@context": "http://schema.org",
"numberOfItems": 2,
"itemListOrder": "Ascending",
"itemListElement": [
{
"@type": "ListItem",
"item": {
"@type": "Thing",
"name": "Thing 1",
"url": "https://api.domain.tld/Thing/?item=1"
},
"position": 1,
"nextItem": "https://api.domain.tld/Thing/?item=2"
},
{
"@type": "ListItem",
"item": {
"@type": "Thing",
"name": "Thing 2",
"url": "https://api.domain.tld/Thing/?item=2"
},
"position": 2,
"previousItem": "https://api.domain.tld/Thing/?item=1"
}
]
}
```