Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/saibotsivad/glopen-routes

Some common routes that I find myself needing often, in glopen format.
https://github.com/saibotsivad/glopen-routes

api glopen openapi

Last synced: about 1 month ago
JSON representation

Some common routes that I find myself needing often, in glopen format.

Awesome Lists containing this project

README 

        
# Glopen Routes



Some common routes that I find myself needing often, in [glopen](https://github.com/saibotsivad/glopen) format, with [JSON:API](https://jsonapi.org/) schemas.



[See the list of route definitions and their functionality.](./definition/README.md)



## Install



The usual way:



```shell

npm install @saibotsivad/glopen-routes

```



To use with `glopen`, you can either include everything in one go, grab individual definitions, or explicitly grab each Operation Object.



(Each definition has an `openapi` folder or a `routes` folder, or both. The `routes` folder separates the Operation Objects out, so they can be explicitly grabbed and still allow merging in the other `openapi` parts. See below for a detailed explanation.)



### Everything At Once



You can use the exported convenience function, which returns a list of all the definitions, ready for use by `glopen`:



```js

// glopen.config.js

import { all } from '@saibotsivad/glopen-routes'

export default {

	merge: [

		...all({

			// Optional: apply the `api` option to all routes.

			api: '/api/v1'

		})

	]

}

```



If you want everything else but don't need team support, you can use `allNoTeams` instead of `all`.



```js

// glopen.config.js

import { allNoTeams } from '@saibotsivad/glopen-routes'

export default {

	merge: [

		...allNoTeams({

			// Optional: apply the `api` option to all routes.

			api: '/api/v1'

		})

	]

}

```



### Individual Definitions



Each definition is a set of interdependent routes, and each is exported as a named function e.g. `singleUser`. See the [full list for details](./definition/README.md).



You will also need to merge in the [shared items](./definition/_shared), which are shared across all routes.



For example, the routes for a single user to manage their own self:



```js

// glopen.config.js

import { shared, singleUser } from '@saibotsivad/glopen-routes'

export default {

	merge: [

		// The shared components are always required

		...shared(),

		// Then each definition

		...singleUser({

			// The definitions can have their API path prefix set

			api: '/api/v1'

		})

	],

}

```



### Explicit Import



If you want to be explicit about each Operation Object that you bring in to your project, or if you want to rename the paths entirely, you can create a file and import->export the route, overwriting the bits that you want.



For example: if you simply want to rename `GET /user` to `GET /currentUser` you could create a folder structure in your project which you would point [glopen](https://github.com/saibotsivad/glopen) to, then create the file like so:



```js

// /currentUser/[email protected]

// First: re-export all the named exports

export * from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/[email protected]'

// Second: re-export the default, which is the route handler

export { default } from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/[email protected]'

```



Additional example: if you also want to customize the `security` and `tags` for each:



```js

// /currentUser/[email protected]

// First: re-export all the named exports

export * from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/[email protected]'

// Second: re-export the default, which is the route handler

export { default } from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/[email protected]'

// Third: exporting `security` here will overwrite whatever was re-exported in the first step

export const security = [ { myBetterAuth: [] } ]

// Fourth: in the same way, exporting `tags` would completely overwrite the re-exported

// tags list. If you want to *merge* the lists, you'll need to import it explicitly, and

// then export the merged list

import { tags as tagsList } from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/[email protected]'

export const tags = [ ...tagsList, 'my-custom-tag' ]

```



**Note:** in your `glopen` config file you'd still need to merge in the shared components and the `openapi` folder for the named definition:



```js

// glopen.config.js

export default {

	merge: [

		// The shared definition parts are always required

		{ dir: './node_modules/@saibotsivad/glopen-routes/definition/_shared/openapi' },

		// For the explicit imported routes, you need to include the `openapi` part

		// to get the component schemas

		{ dir: './node_modules/@saibotsivad/glopen-routes/definition/basic-user-auth/openapi' },

		// Finally, merge in your own project routes

		{ dir: '' },

	],

}

```



Using this approach can be a bit tedious, since you would need to recreate the folder structure for all route methods, e.g. in the `basic-user-auth` there are at least ten (10) files, and you'd need to create all ten in order to have all functionality explicitly named.



One shortcut to note is that `glopen` will merge first-to-last, so as long as you aren't *renaming* any files, you could be explicit with one or two Operation Objects, then merge the named definition first and your explicit folder last, and yours would end up overwriting the original.



## Design



The route handlers are async and take a request object with a properties that need to be initialized prior to executing the handler function:



- `body: Object` - The request body for all these routes is JSON so, for routes that need it, you'll need a body-parser that parses the JSON in advance.

- `controller: Object` - The set of initialized controllers, which are essentially the functions that do the actual work, like `user.create`. (Each route lists the controllers it requires.)



Instead of setting properties on a response object, like Express etc., these route handlers return an object with the following properties:



- `status: Number` - The response status code.

- `headers: Object` - These headers should be merged with any other headers, overwriting base headers if any exist.

- `body: Object | String | null` - The response body, if it exists.

- `json: Boolean` - The response `body` must be passed through a JSON stringify function prior to being returned.



Here is a little demo to show you how you might instantiate and handle a request:



```js

// You'll need to instantiate controllers in advance (or use lazy instantiation techniques).

const controller = {

	demo: {

		getDemo: async (request) => {

			if (request.headers['X-API-Token'] === 'battery-horse-staple') {

				return [ 'first', 'second' ]

			} else {

				return [ 'third', 'fourth' ]

			}

		}

	}

}

// This is what one of the handlers from this project might look like.

const demoRequestHandler = async request => {

	// The controllers are assumed to be instantiated already.

	const data = await request.controller.demo.getDemo(request)

	return {

		status: 200,

		json: true,

		body: { data }

	}

}

// This is a very naive approach, but shows the fundamentals.

import http from 'http'

const server = http.createServer((request, response) => {

	request.controller = controller

	demoRequestHandler(request).then(({ status, json, body }) => {

		response.statusCode = status

		if (json) {

			response.setHeader('Content-Type', 'application/json')

			response.end(JSON.stringify(body))

		} else {

			response.end(body)

		}

	})

})

```



## License



Published and released under the [Very Open License](http://veryopenlicense.com).



If you need a commercial license, [contact me here](https://davistobias.com/license?software=glopen-routes).