{"id":17772622,"url":"https://github.com/jamesplease/api-pls","last_synced_at":"2025-03-15T16:31:41.130Z","repository":{"id":57181536,"uuid":"80494407","full_name":"jamesplease/api-pls","owner":"jamesplease","description":"Need a backend? Just say please","archived":false,"fork":false,"pushed_at":"2017-04-09T21:07:07.000Z","size":482,"stargazers_count":10,"open_issues_count":26,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-14T02:03:52.829Z","etag":null,"topics":["javascript","json-api","node","postgresql","rest","rest-api"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/jamesplease.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}},"created_at":"2017-01-31T05:33:28.000Z","updated_at":"2023-03-10T08:28:25.000Z","dependencies_parsed_at":"2022-09-14T06:00:42.790Z","dependency_job_id":null,"html_url":"https://github.com/jamesplease/api-pls","commit_stats":null,"previous_names":["jmeas/api-pls"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesplease%2Fapi-pls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesplease%2Fapi-pls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesplease%2Fapi-pls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesplease%2Fapi-pls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesplease","download_url":"https://codeload.github.com/jamesplease/api-pls/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243760103,"owners_count":20343622,"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":["javascript","json-api","node","postgresql","rest","rest-api"],"created_at":"2024-10-26T21:40:05.794Z","updated_at":"2025-03-15T16:31:40.796Z","avatar_url":"https://github.com/jamesplease.png","language":"JavaScript","readme":"# api-pls\n\n[![Travis build status](http://img.shields.io/travis/jmeas/api-pls.svg?style=flat)](https://travis-ci.org/jmeas/api-pls)\n[![Test Coverage](https://codeclimate.com/github/jmeas/api-pls/badges/coverage.svg)](https://codeclimate.com/github/jmeas/api-pls)\n\napi-pls enables you to effortlessly create\n[JSON API](http://jsonapi.org/)-compliant APIs.\n\n\u003e Note: this project is a work in progress. It currently functions in a limited\n  manner.\n\n### Motivation\n\nIt requires a lot of knowledge and time to put together a robust backend.\napi-pls is intended to speed up that process considerably.\n\nInstead of writing boilerplate database and API code within your project, simply\ndefine models, and let this tool do the rest.\n\napi-pls will:\n\n✓ Configure a database for you  \n✓ Set up a web server that adheres to JSON API for interactions with those resources  \n✓ ~~Create and run migrations for you when you change your resource models~~   \n\nThis project is a work in progress. Resource migrations beyond the initial\nset up are currently unsupported.\n\n### Table of Contents\n\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [CLI API](#cli-api)\n- [Programmatic API](#programmatic-api)\n- [JSON API Feature Support](#json-api-feature-support)\n- [Technologies Used](#technologies-used)\n- [FAQ](#frequently-asked-questions)\n- [Acknowledgements](#acknowledgements)\n- [Resource Model Definition ⇗](https://github.com/jmeas/api-pls/wiki/Resource-Model)\n- [Contributing Code ⇗](https://github.com/jmeas/api-pls/wiki/Contributing-code)\n- [Examples ⇗](https://github.com/jmeas/api-pls/wiki/Example-Projects)\n\n### Installation\n\nInstall api-pls into your project using [npm](https://www.npmjs.com/).\n\n```\nnpm install api-pls --save\n```\n\nThis package comes with a programmatic interface as well as a command line tool.\n\n### Getting Started\n\napi-pls is a system that reads configuration files that you write, called\nResource Models, and uses those to run migrations on your database. It also\nhas the ability to start an API based on your Resource Models.\n\nThe intent of api-pls is for you to replace database and API code in your\nweb application with these declarative descriptions of resources.\n\nFor complete documentation on Resource Models, refer to the:\n\n[**Resource Model documentation**](https://github.com/jmeas/api-pls/wiki/Resource-Model).\n\nAfter your Resource Models are created, you are ready to start using api-pls.\n\n\u003e Note: you technically don't _need_ Resource Models to use any of the commands\n  in api-pls, but nothing interesting happens unless you have at least one\n  Resource Model.\n\n#### CLI API\n\nThe name of the CLI program is `pls`. The rest of this guide assumes that\n`pls` is on your path. If you've installed it locally into a project, then\nyou will need to call it from within an\n[npm script](https://docs.npmjs.com/misc/scripts#path).\n\n#### Commands\n\n| Command          | Description                                   |\n|----------------- |---------------------------------------------  |\n| reset-database   |  Removes all tables from the database         |\n| sync             |  Synchronize the DB with your Resource Models |\n| start            |  Starts up the API webserver.                 |\n\n#### CLI Flags\n\nAll of the options may also be specified in `.plsrc`, if you would prefer. You\nmay also specify the `DATABASE_URL` in a `.env` file in the directory that you\ncall this command from.\n\n| Flags            | Default     | Description                                 |\n|----------------- |-------------|---------------------------------------------|\n| -h, --help       | N/A         | View all the commands from the command line |\n| -v, --version    | N/A         | Display the version of api-pls              |\n| -d, --database   |             | Specify the database URL                    |\n| -p, --port       | 5000        | Configure the port of the webserver         |\n| -r, --resources  | ./resources | Set the directory of your resources         |\n| -s, --ssl        | true        | Whether or not to connect to the DB with SSL|\n| -a, --api-version| 1           | The API version. It appears in the API URLs |\n| -f, --force      | N/A         | Proceed with the action without confirmation|\n| --silent         | N/A         | Disable logging                             |\n| --verbose        | N/A         | Enable verbose logging                      |\n\n#### Example CLI Usage\n\nThe following example turns off SSL, sets the port to be 6000, and sets the\nresource directory.\n\n```sh\npls start -p 6000 -s false -r ./my-resources\n```\n\n#### Programmatic API\n\nThe module exports a constructor, `ApiPls`.\n\n##### `ApiPls( options )`\n\nReturns an instance of ApiPls. Valid options are:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n|**resourcesDirectory**| ./resources |A string that is the location of your resource models.|\n|**databaseUrl**|      |The URL of the database to connect to.|\n|**connectWithSsl**| true | Whether or not to use SSL to connect to the database.|\n|**port**| 5000 | The port to start the webserver on.|\n|**apiVersion**| 1 | The version of the API. Appears in API URLs.|\n|**silent**| false | Disables all logging from the web server when `true`. |\n|**verbose**| false | Set to `true` to make the server to log more information.|\n\n##### `apiPls.sync()`\n\nSynchronizes your data with the Resource Models in `resourcesDirectory`. Any\ndata in dropped columns will be discarded.\n\nTo transform data in your database, such as moving it between columns or\nupdating all of the data in a single column, see Migrations (coming soon!).\n\n##### `apiPls.start()`\n\nStarts the web server. Typically you'll want to run `sync` before doing\nthis to make sure that the database is up-to-date.\n\n##### `apiPls.dangerouslyResetDatabase()`\n\nRemoves all tables, and therefore, all of the data, from the database. This can\nbe useful for testing. Be careful out there.\n\n##### `apiPls.apiRouter()`\n\nReturns an Express router that can be mounted to any Express server to host an\napi-pls API.\n\n##### `apiPls.db`\n\nAn instance of the Database object from\n[pg-promise](https://github.com/vitaly-t/pg-promise).\n\n#### Static Methods\n\nThese are methods that are attached to the `ApiPls` constructor. If you're\nwriting libraries, plugins, or extensions to api-pls, then you might find these\nuseful. Otherwise, you may never use them.\n\n##### `ApiPls.loadResourceModels( resourcesDirectory )`\n\nLoads all of the resource models from `resourcesDirectory`, which is a string\nthat is the directory to load from.\n\n##### `ApiPls.normalizeModel( resourceModel )`\n\nAccepts a `resourceModel`, such as one returned from\n`ApiPls.loadResourceModels()`, and formats it into a normalized tree. If you're\nwriting custom code to work with resource models, then this can make that\neasier for you.\n\n##### `ApiPls.validateResourceModel( resourceModel )`\n\nAccepts a `resourceModel`, and determines if it is valid or not. If you're\nwriting custom logic around resource models, then this can be useful to catch\nerrors in user-input resource models early on.\n\n#### Example Programmatic Usage\n\n```js\nimport ApiPls from 'api-pls';\n\nconst apiPls = new ApiPls({\n  DATABASE_URL: process.ENV.DATABASE_URL,\n})\n\n// Sync the database, then start the server.\napiPls.sync()\n  .then(() =\u003e apiPls.start());\n```\n\n### JSON API Feature Support\n\nThis project only partially supports JSON API. Features currently supported are:\n\n- [x] CRUD'ing resources\n- [x] Attributes\n- [x] Meta\n- [x] Consistent errors\n- [x] Sparse fieldsets\n- [ ] Sorting\n- [x] Pagination\n- [ ] Filtering\n- [ ] Compound documents\n- [x] Links\n- [ ] Relations\n  - [x] One-to-one\n  - [x] Many-to-one\n  - [ ] Many-to-many\n  - [ ] Relationship endpoints (`/v1/:resource/relationships/:related`)\n  - [ ] Related endpoints (`/v1/:resource/:id/:related`)\n\n### Technologies Used\n\nCurrently, the only supported database is\n[PostgreSQL](https://www.postgresql.org/). The webserver is written\nin [Node.js](https://nodejs.org/en/) using\n[Express](https://github.com/expressjs/express).\n\n### FAQ\n\n#### Who is the target audience for api-pls?\n\nIt is my hope that engineers of all skill levels could find value in api-pls.\n\nEngineers who may not feel confident in building a backend can use api-pls to\nget up-and-running quickly. They might even use api-pls as the entire backend\nfor an application.\n\nMore confident engineers might find that api-pls is sufficient for some of the\nresources in an application they are building, so they may leverage it for\nthose resources. And because api-pls tables can coexist with manually managed\ntables, there's no issue in only using api-pls for part of an application.\n\n### Acknowledgements\n\n[Tyler Kellen](https://github.com/tkellen) for his work on\n[Endpoints](https://github.com/endpoints/endpoints) (which inspired me to write\nthis) and for our many conversations about REST.\n\n[Eric Valadas](https://github.com/ericvaladas) for helping plan the API and\nimplementation of this library.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesplease%2Fapi-pls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesplease%2Fapi-pls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesplease%2Fapi-pls/lists"}