Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/issue 1007 api routes #1017

Merged
merged 20 commits into from
Dec 17, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
add API routes documentation
thescientist13 committed Dec 14, 2022
commit 0c6c2f978699bae3186ef940a9df1441bfe8a67b
78 changes: 78 additions & 0 deletions www/pages/docs/api-routes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
label: 'API-routes'
menu: side
title: 'API Routes'
index: 9
linkheadings: 3
---

## API Routes

Greenwood has support for API routes, which are just functions that run on the server, and take in a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).

### Usage

API routes follow a file based routing convention, just like [pages](/docs/layouts/#pages). So this structure
```shell
src/
api/
greeting.js
```

Will yield an endpoint available at `/api/greeting`.

Here is an example of that API, which ready a query parameter of `name` and returns a JSON response.

```js
export async function handler(request) {
const params = new URLSearchParams(request.url.slice(request.url.indexOf('?')));
const name = params.has('name') ? params.get('name') : 'World';
const body = { message: `Hello ${name}!!!` };

return new Response(JSON.stringify(body), {
headers: {
'Content-Type': 'application/json'
}
});
}
```

### WCC

As [WCC](https://github.com/ProjectEvergreen/wcc) already comes with Greenwood, it can be used to generate HTML on the fly for over the wire transmission to the browser. This is great for generating HTML "fragments" on the server side using Web Components, thus being able to leverage your components on the client _and_ the server! As the HTML is added the DOM, if the custom element definition has been loaded client side too, these components will hydrate automatically and become instantly interactive. (think of appending more items to a virtualized list). 🚀

An example of rendering a "card" component in an API route might look like look this.
```js
// card.js
export default class Card extends HTMLElement {
connectedCallback() {
const name = this.getAttribute('name');

this.innerHTML = `
<h1>Hello ${name}!!!</h1>
`;
}
}

customElements.define('x-card', Card);
```

```js
// API route
import { renderFromHTML } from 'wc-compiler';

export async function handler(request) {
const headers = new Headers();
const params = new URLSearchParams(request.url.slice(request.url.indexOf('?')));
const name = params.has('name') ? params.get('name') : 'World';
const { html } = await renderFromHTML(`
<x-card name="${name}"></x-card>
`, [
new URL('../components/card.js', import.meta.url)
]);

headers.append('Content-Type', 'text/html');

return new Response(html, { headers });
}
```
2 changes: 1 addition & 1 deletion www/pages/docs/data.md
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@
label: 'data-sources'
menu: side
title: 'Data Sources'
index: 10
index: 11
linkheadings: 3
---

2 changes: 1 addition & 1 deletion www/pages/docs/menus.md
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@
label: 'menus'
menu: side
title: 'Menus'
index: 9
index: 10
linkheadings: 3
---