{"id":13471026,"url":"https://github.com/apiaryio/protagonist","last_synced_at":"2025-12-30T03:01:52.013Z","repository":{"id":7871617,"uuid":"9244177","full_name":"apiaryio/protagonist","owner":"apiaryio","description":"Protagonist is Node.js wrapper for the API Blueprint parser","archived":true,"fork":false,"pushed_at":"2024-07-15T16:08:04.000Z","size":492,"stargazers_count":354,"open_issues_count":4,"forks_count":30,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-03-16T18:32:07.612Z","etag":null,"topics":["api-blueprint","nodejs-library","nodejs-modules"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apiaryio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2013-04-05T15:29:18.000Z","updated_at":"2025-02-10T00:41:50.000Z","dependencies_parsed_at":"2024-10-08T15:48:03.878Z","dependency_job_id":"774b4d21-e85a-4c38-9a40-fbd7d905e457","html_url":"https://github.com/apiaryio/protagonist","commit_stats":{"total_commits":390,"total_committers":23,"mean_commits":"16.956521739130434","dds":0.7487179487179487,"last_synced_commit":"4c5c0217a2058eb88e22d52eead617e256ee23ea"},"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fprotagonist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fprotagonist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fprotagonist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fprotagonist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apiaryio","download_url":"https://codeload.github.com/apiaryio/protagonist/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245662710,"owners_count":20652068,"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-blueprint","nodejs-library","nodejs-modules"],"created_at":"2024-07-31T16:00:38.564Z","updated_at":"2025-12-18T00:29:59.970Z","avatar_url":"https://github.com/apiaryio.png","language":"C++","readme":"![logo](https://raw.github.com/apiaryio/api-blueprint/master/assets/logo_apiblueprint.png)\n\n# Protagonist - API Blueprint Parser for Node.js\n\n[![AppVeyor](https://ci.appveyor.com/api/projects/status/uaa6ivk97urmoucr/branch/master?svg=true)](https://ci.appveyor.com/project/Apiary/protagonist)\n\nProtagonist is a Node.js wrapper for the\n[Drafter](https://github.com/apiaryio/drafter), an API Blueprint parser. [API\nBlueprint](https://apiblueprint.org) is a language for describing web APIs.\n\n## Install\n\n**NOTE:** *For general use we recommend that you use the [Drafter\nNPM](https://github.com/apiaryio/drafter-npm) package instead of Protagonist\ndirectly as Protagonist needs to be compiled which may not be possible in every\nsituation.*\n\nProtagonist can be installed via the [Protagonist npm\npackage](https://npmjs.org/package/protagonist) by\n[npm](https://docs.npmjs.com/cli/npm) or [yarn](https://yarnpkg.com/en/).\n\n```sh\n$ npm install protagonist\n# or\n$ yarn install protagonist\n```\n\nProtagonist uses the\n[node-gyp](https://github.com/nodejs/node-gyp#installation) build tool which\nrequires Python 2.7 (3.x is not supported) along with a compiler and other\nbuild tools. Take a look at their installation steps for\n[Linux](https://github.com/nodejs/node-gyp#on-unix),\n[macOS](https://github.com/nodejs/node-gyp#on-macos), and\n[Windows](https://github.com/nodejs/node-gyp#on-windows).\n\n## Usage\n\nProtagonist offers the ability to both validate, and parse an API Blueprint.\nIt offers the following APIs:\n\n- [`validate(source, options)`](#validate)\n- [`validateSync(source, options)`](#validate-sync)\n- [`parse(source, options)`](#parse)\n- [`parseSync(source, options)`](#parse-sync)\n\n**NOTE:** *It is not recommended to use the synchronous APIs as they can block\nthe Node.JS event loop.*\n\n\u003ca name=\"validate\"\u003e\u003c/a\u003e\n### Validating an API Blueprint\n\nYou can validate an API Blueprint to determine if the source is a valid\ndocument. The parse result will contain any errors or warnings that the\ndocument would emit during parsing.\n\n```js\nconst protagonist = require('protagonist');\n\nconst parseResult = await protagonist.parse('# My API');\nconsole.log(JSON.stringify(parseResult, null, 2));\n```\n\nor by using Promises:\n\n```js\nconst protagonist = require('protagonist');\n\nprotagonist.validate('# My API')\n  .then((parseResult) =\u003e {\n    console.log(JSON.stringify(parseResult, null, 2));\n  })\n  .catch((error) =\u003e {\n    console.error(error);\n  });\n```\n\nSee the [parse result](#parse-result) section below for more information about\nthe structure of the parse result.\n\n\u003ca name=\"validate-sync\"\u003e\u003c/a\u003e\n#### Synchronous API\n\n```js\nconst protagonist = require('protagonist');\nconst parseResult = protagonist.validateSync('# My API');\n```\n\n#### Validation Options\n\nOptions can be passed to the parser as an optional second argument to both the asynchronous and synchronous interfaces:\n\n```js\nconst protagonist = require('protagonist');\n\nconst options = {\n  requireBlueprintName: true,\n};\nconst parseResult = await protagonist.validate('# My API', options);\n```\n\nThe available options are:\n\nName                   | Description\n---------------------- | ----------------------------------------------------------\n`requireBlueprintName` | Require parsed blueprints have a title (default: false)\n\n\u003ca name=\"parse\"\u003e\u003c/a\u003e\n### Parsing an API Blueprint\n\nYou can parse an API Blueprint with async/await:\n\n```js\nconst protagonist = require('protagonist');\n\nconst parseResult = await protagonist.parse('# My API');\nconsole.log(JSON.stringify(parseResult, null, 2));\n```\n\nor by using Promises:\n\n```js\nconst protagonist = require('protagonist');\n\nprotagonist.parse('# My API')\n  .then((parseResult) =\u003e {\n    console.log(JSON.stringify(parseResult, null, 2));\n  })\n  .catch((error) =\u003e {\n    console.error(error);\n  });\n```\n\nSee the [parse result](#parse-result) section below for more information about\nthe structure of the parse result.\n\n\u003ca name=\"parse-sync\"\u003e\u003c/a\u003e\n#### Synchronous API\n\n```js\nconst parseResult = protagonist.parseSync('# My API');\n```\n\n#### Parsing Options\n\nOptions can be passed to the parser as an optional second argument to both the asynchronous and synchronous interfaces:\n\n```js\nconst options = {\n  generateSourceMap: true,\n  generateMessageBody: true,\n  generateMessageBodySchema: true,\n};\nconst parseResult = await protagonist.parse('# My API', options);\n```\n\nThe available options are:\n\nName                        | Description\n--------------------------- | ----------------------------------------------------------\n`requireBlueprintName`      | Require parsed blueprints have a title (default: false)\n`generateSourceMap`         | Enable sourcemap generation (default: false)\n`generateMessageBody`       | Enable generation of messageBody from MSON (default: true)\n`generateMessageBodySchema` | Enable generation of messageBodySchema from MSON (default: true)\n\n\u003ca name=\"parse-result\"\u003e\u003c/a\u003e\n### Parse Result\n\nThe format of the parse result is an [API Elements](https://apielements.org/)\nstructure, there is also [API Elements:\nJS](https://github.com/apiaryio/api-elements.js) which contains tooling to\nhandle this format in JavaScript. It is recommended to use the provided API\nElements tooling to [prevent any tight\ncoupling](http://apielements.org/en/latest/overview.html#consuming-documents)\nbetween your tool and a parse result.\n\nAs an example, parsing the following API Blueprint:\n\n```apib\n# GET /\n+ Response 204\n```\n\nWould result in the following [API Elements Parse\nResult](http://apielements.org/en/latest/element-definitions.html#parse-result-element-types):\n\n```json\n{\n  \"element\": \"parseResult\",\n  \"content\": [\n    {\n      \"element\": \"category\",\n      \"meta\": {\n        \"classes\": {\n          \"element\": \"array\",\n          \"content\": [\n            {\n              \"element\": \"string\",\n              \"content\": \"api\"\n            }\n          ]\n        },\n        \"title\": {\n          \"element\": \"string\",\n          \"content\": \"\"\n        }\n      },\n      \"content\": [\n        {\n          \"element\": \"resource\",\n          \"meta\": {\n            \"title\": {\n              \"element\": \"string\",\n              \"content\": \"\"\n            }\n          },\n          \"attributes\": {\n            \"href\": {\n              \"element\": \"string\",\n              \"content\": \"/\"\n            }\n          },\n          \"content\": [\n            {\n              \"element\": \"transition\",\n              \"meta\": {\n                \"title\": {\n                  \"element\": \"string\",\n                  \"content\": \"\"\n                }\n              },\n              \"content\": [\n                {\n                  \"element\": \"httpTransaction\",\n                  \"content\": [\n                    {\n                      \"element\": \"httpRequest\",\n                      \"attributes\": {\n                        \"method\": {\n                          \"element\": \"string\",\n                          \"content\": \"GET\"\n                        }\n                      },\n                      \"content\": []\n                    },\n                    {\n                      \"element\": \"httpResponse\",\n                      \"attributes\": {\n                        \"statusCode\": {\n                          \"element\": \"string\",\n                          \"content\": \"204\"\n                        }\n                      },\n                      \"content\": []\n                    }\n                  ]\n                }\n              ]\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Developing Protagonist\n\nYou can use the following steps to build and test Protagonist.\n\n```sh\n$ git clone --recursive https://github.com/apiaryio/protagonist.git\n$ cd protagonist\n$ npm install\n```\n\nWhile iterating on the package, you can use `npm run build` to compile\nProtagonist:\n\n```sh\n$ npm run build\n$ npm test\n```\n\nProtagonist is built using [node-gyp](https://github.com/nodejs/node-gyp), you\ncan consult their documentation for further information on the build system.\n\n## License\n\nMIT License. See the [LICENSE](https://github.com/apiaryio/protagonist/blob/master/LICENSE) file.\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fprotagonist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapiaryio%2Fprotagonist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fprotagonist/lists"}