{"id":18868931,"url":"https://github.com/ndlano/article-api","last_synced_at":"2025-04-14T15:31:09.294Z","repository":{"id":45384399,"uuid":"66824916","full_name":"NDLANO/article-api","owner":"NDLANO","description":"DEPRECATED! Moved into the backend monorepo: https://github.com/NDLANO/backend. API for accessing articles from NDLA","archived":true,"fork":false,"pushed_at":"2022-11-08T13:26:48.000Z","size":2864,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-02-20T10:14:56.338Z","etag":null,"topics":["accessing-articles","article","article-api","elasticsearch","ndla"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NDLANO.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":"2016-08-29T08:17:40.000Z","updated_at":"2024-04-19T07:33:28.000Z","dependencies_parsed_at":"2022-09-09T16:00:38.542Z","dependency_job_id":null,"html_url":"https://github.com/NDLANO/article-api","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NDLANO%2Farticle-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NDLANO%2Farticle-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NDLANO%2Farticle-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NDLANO%2Farticle-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NDLANO","download_url":"https://codeload.github.com/NDLANO/article-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248906408,"owners_count":21181174,"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":["accessing-articles","article","article-api","elasticsearch","ndla"],"created_at":"2024-11-08T05:15:16.294Z","updated_at":"2025-04-14T15:31:06.783Z","avatar_url":"https://github.com/NDLANO.png","language":"Scala","readme":"# ARTICLE API \n![CI](https://github.com/NDLANO/article-api/workflows/CI/badge.svg)\n\n## Usage\nCreates, updates and returns an `Article`. Implements Elasticsearch for search within the article database.\n\nTo interact with the api, you need valid security credentials; see [Access Tokens usage](https://github.com/NDLANO/auth/blob/master/README.md).\nTo write data to the api, you need write role access.\n\nIt also has as internal import routines for importing data from the old system to this database. There are a number of cleaning and\nreporting services pertaining to the import which are only available for internal admin services. \n\nThe application can be configured by specifying several parameters as environment variables. See `src/main/scala/no/ndla/articleapi/ArticleApiProperties.scala` for full list.\n\n## Article format\nThe endpoint `GET /article-api/v2/articles/\u003cid\u003e` will fetch a json-object containing the article in the selected language.\nThe article body contained in this json-object consists of a strict subset of permitted HTML tags. It may also contain a special tag, `\u003cembed\u003e`,\nwhich is used to refer to content located in other APIs (including, but not limited to images, audio, video and H5P).\n\nSome example usages of the embed tag:\n* `\u003cembed data-resource=\"external\" data-url=\"https://youtu.be/7ZVyNjKSr0M\" data-id=\"0\" /\u003e` refers content from an external source (data-resource). In this case Youtube.\n  `data-url` is the url where the resource can be found, `data-id` is an embed tag-identifier used to identify unique embeds in this article and is located in every embed tag.\n* `\u003cembed data-align=\"\" data-alt=\"Fyrlykt med hav og horisont\" data-caption=\"\" data-resource=\"image\" data-size=\"fullbredde\" data-id=\"1\" data-url=\"http://image-api-url/image-api/v1/images/179\" /\u003e`\n  refers to an image (`data-resource`) located in the [image API](https://github.com/NDLANO/image-api), along with alignment info (`data-align`), alternative text (`data-alt`),\n  image caption (`data-caption`), intended display size in the article (`data-size`), the unique embed tag-identifier (`data-id`) and the url where image metadata can be found (`data-url`).\n\nIn order to display the article in its intended form all these embed-tags needs to be parsed and replaced with the content from its respectable source.\nThe [article converter](https://github.com/NDLANO/article-converter) implements the logic needed to do this.\n\n\nFor a more detailed documentation of the API, please refer to the [API documentation](https://api.ndla.no) (Staging: [API documentation](https://api.staging.ndla.no)).\n\n### Validation of article content\n\nWhenever an article is created or updated a validation of the content itself is performed. This is to ensure that only accepted tags and attributes are\nused.\nA list of permitted HTML/MathML tags and attributes are specified in the repo [validation](https://github.com/NDLANO/validation) in the files `src/main/resources/html-rules.json` and `src/main/resources/mathml-rules.json`.\nThe `tags` section defines permitted tags without attributes. The `attributes` section defines tags with a list of permitted attributes.\n\nExtra validation is performed on the `\u003cembed\u003e` tag: based on the `data-resource` attribute a different set of **required** attributes must also be present.\nThese rules are defined in `src/main/resources/embed-tag-rules.json` in validation-repo. Should any attribute other than those in the required list be present,\nthey will be stripped before validation (this step is only performed on `\u003cembed\u003e` tags).\n\nWhen an article is fetched with the `GET` API endpoint, the api will add a `data-url` attribute on every `\u003cembed\u003e` tag which also contains a `data-resource_id` attribute.\nA `data-id` attribute is appended to each `\u003cembed\u003e` tag.\n\n### Resource types for embed tags\nThe embed tag contains a set of attributes which define what content should be inserted. The list below provides an explaination of each recognized attribute.\n\n#### Required Attributes\n\n* **data-resource** - defines the type of resource that should be inserted (can be image, audio, link to another article, ...). Present in every embed tag\n* **data-id** - a unique number identifying the embed tag in an article. Present in every embed tag\n* **data-url** - a url linking to the resource to insert. Present in image, audio, h5p, external, and nrk\n* **data-path** - a path linking to the resource to insert. Present in h5p\n* **data-alt** - alternative text to display if the resource could not be inserted. Present in image\n* **data-size** - a hint as to how large the resource should be when presented. Present in image\n* **data-align** - a hint as to the alignment of the resource when presented. Can be \"left\" or \"right\". Present in image\n* **data-player** - a video player identifier used to play videos. Present in brightcove\n* **data-message** - a message to be displayed when presented. Present in error\n* **data-caption** - a caption to display along with the resource. Present in brightcove and image\n* **data-account** - the brightcove account id. Present in brightcove\n* **data-videoid** - a video identifier. Present in brightcove\n* **data-link-text** - the text to display in a link. Present in content-link and concept\n* **data-content-id** - the id to the article content to be inserted. Present in content-link and concept\n* **data-content-type** - the type of the content-link to be inserted. Internal or external\n* **data-nrk-video-id** - an ID to nrk videos. Present in nrk\n* **data-resource_id** - an ID to an internal resource to be inserted. Present in image and audio\n* **data-type** - specifies inline or block concept embed. Present in concept\n* **data-code-format** - specifies format of code-block embed. Present in code-block\n* **data-code-content** - specifies content of code-block embed. Present in code-block\n\n#### Optional attributes\n\nOptional attribute groups are defined in the validatin library [here](https://github.com/NDLANO/validation/blob/master/src/main/resources/embed-tag-rules.json).\nEvery attribute in an attribute group must be specified. Otherwise validation will fail.\nThe following attribute groups exists:\n* `data-open-in`: Can only be used for content embed-tags\n* `data-upper-left-x`, `data-upper-left-y`, `data-lower-right-x`, `data-lower-right-y`: Can only be used for image embed-tags\n* `data-focal-x`, `data-focal-y`: Can only be used for image embed-tags\n* `data-title`: Can only be used for code-block embed-tags. Specifies title of code-block\n* `data-display`: Can only be used with file. Used to specify inline display of PDF-files. \n\n### Other tags with extra attributes\nThe following tags may contain extra attributes which conveys information about how they should be displayed\n* `ol`\n  * **data-type** - If present and with the value \"letters\" the bullets should be letters.\n* `aside`\n  * **data-type** - Specifies how the aside should be viewed\n* `embed` resource=concept\n  * **data-type** - Specifies type of concept embed. Either inline or as block\n\n## Developer documentation\n\n**Compile**: sbt compile\n\n**Run tests:** sbt test\n\n**Run pact provider verification tests:** sbt \"pact:testOnly -- -n PactProviderTest\"\n\n**Create Docker Image:** sbt docker\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndlano%2Farticle-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fndlano%2Farticle-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndlano%2Farticle-api/lists"}