{"id":16767727,"url":"https://github.com/xiaohutai/jsonapi","last_synced_at":"2025-03-21T23:33:48.900Z","repository":{"id":33151189,"uuid":"36791125","full_name":"xiaohutai/jsonapi","owner":"xiaohutai","description":"[Bolt Extension] JSON API for Bolt CMS","archived":false,"fork":false,"pushed_at":"2020-05-01T12:40:17.000Z","size":234,"stargazers_count":55,"open_issues_count":10,"forks_count":18,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-10-14T06:09:46.885Z","etag":null,"topics":["api","bolt","extension","json","jsonapi"],"latest_commit_sha":null,"homepage":"https://market.bolt.cm/view/bolt/jsonapi","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"Microsoft/ChakraCore","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xiaohutai.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-03T08:42:26.000Z","updated_at":"2023-12-15T16:28:11.000Z","dependencies_parsed_at":"2022-06-27T07:12:47.284Z","dependency_job_id":null,"html_url":"https://github.com/xiaohutai/jsonapi","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaohutai%2Fjsonapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaohutai%2Fjsonapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaohutai%2Fjsonapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaohutai%2Fjsonapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiaohutai","download_url":"https://codeload.github.com/xiaohutai/jsonapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221820606,"owners_count":16886222,"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","bolt","extension","json","jsonapi"],"created_at":"2024-10-13T06:09:44.975Z","updated_at":"2024-10-28T11:15:35.029Z","avatar_url":"https://github.com/xiaohutai.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"JSON API\n========\n\nProvides simple JSON access to Bolt's internal data structures. The specification\nof the JSON responses are based on [JSON API](http://jsonapi.org/).\n\nEnabling this extension adds routes to the application that serves content as\nJSON rather than HTML. This route defaults to `/json`, so if, for example, you\nhave a contenttype named `entries`, then the entry with ID 1 is available\nunder `/json/entries/1`.\n\nConfiguration\n-------------\n\nIn order to enable JSON serving for any contenttype, it has to be added to the\nextension's configuration file, located at `app/config/extensions/jsonapi.bolt.yml`.\n\nNote in particular that contenttypes that you don't mention in the\nconfiguration file won't be served by the JSON API extension.\n\n### Base URL\n\nOverriding the `base` setting allows you to customize where the API is\naccessible from. This defaults to `/json`.\n\n```YML\nbase: '/json'\n```\n\n### Contenttypes\n\nOnly contenttypes listed under `contenttypes` in the config will be served; for\nany other contenttype, the API will return 404 errors.\n\nBesides errors, there are two types of responses you can receive, a `list` of\nitems or single `item`. You can customize the fields shown in the responses with\n`list-fields` and `item-fields` respectively.\n\nBoth field names and taxonomy names are supported. If a field and a taxonomy\nshare the same names, both will be included. Taxonomy values are always under\nthe `taxonomy` property under `attributes`, whereas _normal_ fields can be found\ndirectly under `attributes`.\n\nTo use the defaults for a contenttype, just leave its entry empty. This will\ninclude all user-defined fields (fields and taxonomies in `contenttypes.yml`),\nthe ID and its contenttype in the listing, but not any of the base fields that\nBolt adds to all contenttypes, such as `datecreated`.\n\nWith JSON API, you can also request which fields are to be returned with\n`?fields[\u003ccontenttype\u003e]=\u003cfield1\u003e,\u003cfield2\u003e`. To limit the options, you can set\n`allowed-fields` in order to filter these. At the moment, `list-fields` and\n`item-fields` ignore the `allowed-fields` setting.\n\nThe `where-clause` setting allows you to set additional conditions that are\nalways set by default.\n\n```YML\ncontenttypes:\n    entries:\n        item-fields: [ title, slug, teaser, image ]\n        list-fields: [ title, slug, teaser, image ]\n        allowed-fields: [ title, slug, teaser, image ]\n        where-clause:\n            status: 'published'\n        order: title,-datepublish\n    pages:\n        # use 'default' settings\n```\n\n### Images\n\nFor images, you'll get an absolute URL to that asset. By default, this extension\nadds an absolute URL to a 400x300 thumbnail in the response. By overriding the\n`thumbnail` setting, you can set a preferred `width` and `height`.\n\n```YML\nthumbnail:\n    width: 400\n    height: 300\n```\n\n### Headers\n\nTo work correctly with other tools that _read_ the JSON generated this extension,\nit might be necessary to set the correct headers with the response. By default,\nthis extension sets the following:\n\n```YML\nheaders:\n    'Access-Control-Allow-Origin': '*'\n    'Content-Type': 'application/vnd.api+json'\n```\n\nYou can define additional headers as required, or tweak the existing ones.\n\n\nQueries\n-------\n\nThis extension implements the [JSON API](http://jsonapi.org/) specification,\nas follows:\n\n| URL         | Description                                                    |\n|-------------|----------------------------------------------------------------|\n|`/{ct}`      | Returns a list of records of the specified `contenttype`.      |\n|`/{ct}/{id}` | Returns a single record of the specified `contenttype`.        |\n|`/{ct}/{id}/{relatedtype}` | Returns a list of records that is related to the specified record with specified `id`. |\n\nwhere `{ct}` means `{contenttype}`, the name of the specified contenttype.\n\n### Query Parameters\n\nThe list call accepts some extra parameters (in the form of query string\nparameters appended to the URL):\n\n| Option       | Description                                                       |\n|--------------|-------------------------------------------------------------------|\n|`sort`        | Order the list by the specified field. Prefix the fieldname with a minus/hyphen to set the orderering to descending. Example `sort=id` or `sort=-id`. Note: Bolt currently does not support sorting on multiple fields. |\n|`page[size]`  | Specify the number of items to return. Example: `page[size]=10` |\n|`page[number]`| To be combined with `page[size]`: get the n-th page. This is 1-based, so `1` designates the first page. Example: `page[number]=1\u0026page[size]=10`. |\n|`include`     | Fetches all the related records of the specified contenttype(s) of the record(s) in the `included` field of the JSON response. Separate multiple contenttypes with a comma. Example: `include=pages`. |\n|`fields[]`    | Set the fields that are shown in the response per specified contenttype. Separate multiple fields with commas. Multiple `fields[]` parameters are possible. Example: `fields[entries]=slug,teaser`. |\n|`filter[]`    | Filter records where a certain field must be equal to the specified `{value}`. Multiple `filter[]` parameters are possible. Example: `filter[id]=1,2`. |\n|`contains[]`  | Filter records where a certain field must contain the specified `{value}`. Multiple `contains[]` parameters are possible. Example: `contains[id]=1,2`. |\n\n\n### Additional Queries\n\nBesides the basic JSON API features, below are some additional Bolt specific\nqueries that you may find useful:\n\n| URL                     | Description                                                 |\n|-------------------------|-------------------------------------------------------------|\n|`/{ct}/search?q={query}` | Searches for `{query}` in a specific `contenttype`.         |\n|`/search?q={query}`      | Searches for `{query}` in all contenttypes.                 |\n|`/menu`                  | Returns a list of all menus defined in `menu.yml`.          |\n|`/menu?q={name}`         | Returns the menu with the specified name.                   |\n|`/taxonomy`              | Returns a list of all taxonomies defined in `taxonomy.yml`. |\n|`/taxonomy?q={name}`     | Returns the taxonomy with the specified name.               |\n\n\nBolt Translate integration\n--------------------------\n\nIn order to use this extension with [bolt/translate](https://github.com/BoltTranslate/Translate).\nSet up the translate as usual. Then, for every query, add a `_locale` parameter, e.g. `/pages?_locale=en`.\n\n\nRoad Map\n--------\n\n  * Better handling of menus.\n  * Better handling of taxonomies.\n  * Better search.\n  * Handle specific fieldtypes:\n    * Handle JSON fields.\n    * Handle select-contenttype fields.\n  * Add hooks for handling specific fieldtypes.\n  * Add i18n for `detail` field in error messages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaohutai%2Fjsonapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaohutai%2Fjsonapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaohutai%2Fjsonapi/lists"}