Enterprise Only

Integrating with Json Placeholder

In this tutorial we will implement a basic integration with Json Placeholder.

We will create a Todo list based on the data from here.

For detailed information about integrating with new APIs please read these docs.

Overview

To add a new data type from a new data source we will need to integrate with a few of Falcon Platform's concepts.

  • APIs (to fetch the data)
  • Extensions (to format the data using GraphQL)
  • Queries (to decide what data is needed)
  • Components (to render the data on the frontend)

n.b. In this tutorial we will be adding everything directly into our repository client/src and server/src. If you plan to reuse your functionality it's highly recommended you add it to your own NPM packages.

1. Add your API connection

We need to create the file server/src/falcon-jsonplaceholder-api/index.js.

Notice the naming convention [package]-[datasource]-api.

In this file we create our fetch requests to the API.

server/src/falcon-jsonplaceholder-api/index.js

const { ApiDataSource } = require('@deity/falcon-server-env');
module.exports = class JsonPlaceholderApi extends ApiDataSource {
async todoList(_, { pagination }) {
const query = {};
if (pagination) {
query._limit = pagination.perPage;
query._start = pagination.page;
}
const todos = await this.get('todos', query);
return {
items: todos
}
}
async todo(_, { id }) {
return this.get(`todos/${id}`);
}
};

There is a lot going on here, some of which will be explained later. It's important we extend ApiDataSource so our core packages can do the heavy lifting.

2. Add your extension and GraphQL schema

Now we need to add our extension. You'll need to create 2 files:

|-server
|-src
|-falcon-todos-extension
index.js
schema.graphql

Again, notice the naming convention. [package]-[data_type]-extension. Unlike the API package, we name this based on the data type not the source. This is because, we may at any point want to swap out the source but use the same extension.

The index.js file can look like this:

server/src/falcon-todos-extension/index.js

module.exports = () => ({});

At this point we don't need to do anything custom here. Provided our queries are named correctly (see below) they will be mapped automatically to our API methods.

Your schema.graphql file should look like this:

server/src/falcon-todos-extension/schema.graphql

extend type Query {
todoList(pagination: PaginationInput): TodoList! @cache(ttl: 15)
todo(id: ID!): Todo! @cache(ttl: 15)
}
type TodoList {
items: [Todo!]!
pagination: Pagination
}
type Todo {
userId: Int
id: ID
title: String
completed: Boolean
}

In this file we are defining what each query should accept and return.

The magic part... notice the name of our 2 queries, they are named todoList and todo. Now go back and look at server/src/falcon-jsonplaceholder-api/index.js. You will notice that the methods share the same name, if you keep the name the same these methods will be bound automatically.

Pagination

We are passing PaginationInput to our todoList query but not defining it. This is already defined in @deity/falcon-data/src/Pagination/Pagination.ts.

It contains to bits of information perPage and page.

@deity/falcon-data/src/Pagination/Pagination.ts

export type PaginationInput = {
perPage: number;
page: number;
};

We map these to query parameters in server/src/falcon-jsonplaceholder-api/index.js.

server/src/falcon-jsonplaceholder-api/index.js

if (pagination) {
query._limit = pagination.perPage;
query._start = pagination.page * pagination.perPage;
}
return this.get('todos', query);

The end result is https://jsonplaceholder.typicode.com/todos?_limit=[perPage]&_start=[page]

3. Include your extension and API

Now we've added our files we need to make sure falcon-server is using them and they are mapped together.

This is done in your server/config/default.json file.

server/config/default.json

{
...
"apis": {
...
"jsonplaceholder": {
"package": "./src/falcon-jsonplaceholder-api/index.js",
"config": {
"host": "jsonplaceholder.typicode.com",
"protocol": "https"
}
}
},
"extensions": {
...
"falcon-todos-extension": {
"package": "./src/falcon-todos-extension",
"config": {
"api": "jsonplaceholder"
}
}
}
}

In this file we define our API (jsonplaceholder) and pass this to our extensions config "api": "jsonplaceholder".

Within the API config we've also defined host and protocol. These are used automatically by the get functions in server/src/falcon-jsonplaceholder-api/index.js.

4. Test your graphQL

You should be all set to test your extension now.

If you've got falcon-server running and it's on port 4000 (this is the default port) then you can test your queries here. If you get results returned then you're in business.

5. Accessing your data in Falcon Client.

Now we need to create query components. You will often see these named like [package]-[data_type]-data e.g. falcon-blog-data.

Because we aren't adding our code to NPM packages we are going to add the code to our client/src/components directory.

|-client
|-src
|-components
|- Todo
index.js
TodoItemQuery.js
TodoListQuery.js

Our index.js file will just be used to export our components.

client/src/components/Todo/index.js

export * from './TodoListQuery';
export * from './TodoItemQuery';

We now need to create a Query component for each data type, TodoItem and TodoList.

client/src/components/Todo/TodoItemQuery.js

import gql from 'graphql-tag';
import { Query } from '@deity/falcon-data';
const GET_TODO_ITEM = gql`
query TodoItem($id: ID!) {
todo(id: $id) {
title
completed
}
}
`;
export class TodoItemQuery extends Query {
static defaultProps = {
query: GET_TODO_ITEM
};
}

In this file we define our GraphQL query and pass it to our component that extends import { Query } from '@deity/falcon-data'.

We are just grabbing title and completed but if you want the id or userId defined in our server/src/falcon-todos-extension/schema.graphql you can.

Our TodoListQuery looks very similar:

client/src/components/Todo/TodoListQuery.js

import gql from 'graphql-tag';
import { Query } from '@deity/falcon-data';
const GET_TODO_LIST = gql`
query TodoList($pagination: PaginationInput) {
todoList(pagination: $pagination) {
items {
title
completed
}
}
}
`;
export class TodoListQuery extends Query {
static defaultProps = {
query: GET_TODO_LIST
};
}

6. Rendering your data in a component

Let's use our data in some components...

todo list component

For this we need to create 2 more components.

|-client
|-src
|-components
|- Todo
TodoItem.js
TodoList.js

We also need to export them from our index.js file.

client/src/components/Todo/index.js

...
export * from './TodoList';
export * from './TodoItem';

Todo Item Component

client/src/components/Todo/TodoItem.js

import React from 'react';
import { TodoItemQuery } from './TodoItemQuery';
export const TodoItem = ({ todoId }) => {
return (
<>
<TodoItemQuery variables={{ id: todoId }}>
{({ data: { todo } }) => {
if (todo) {
return <h1>{todo.title}</h1>;
}
return null;
}}
</TodoItemQuery>
</>
);
};

There is a few things going on here. We import our TodoItemQuery component.

This accepts a variables prop. This is an object of variables that are passed to our query. In this case, the ID of our todo.

Each query returns data, this returns the response from our query...in our case, todo.

Todo List Component

client/src/components/Todo/TodoList.js

import React from 'react';
import { TodoListQuery } from './TodoListQuery';
export const TodoList = ({ pagination = {} }) => {
return (
<>
<TodoListQuery variables={{ pagination }}>
{({ data: { todoList = {} } }) => {
const { items = [] } = todoList;
if (items.length) {
const todoItems = items.map(item => {
const { completed, title } = item;
return completed ? (
<li>{title}</li>
) : (
<li>
<del>{title}</del>
</li>
);
});
return <ul>{todoItems}</ul>;
}
return null;
}}
</TodoListQuery>
</>
);
};

This works in exactly the same way as our TodoItem component.

7. Use our components.

We've done all the hard work, we now just need to use our components somewhere in our application.

To access our component in an standardized way we will first export it to the component root.

client/src/components/index.js

...
export * from './Todo';

Now that it is available from the components directory I'm going to add them to the homepage.

client/src/pages/home/Home.js

...
import {
TodoItem,
TodoList
} from '../../components';
const Home = () => {
...
return (
<PageLayout css={{ paddingTop: 72, paddingBottom: 72, gridGap: 72 }}>
...
<TodoItem todoId={2} />
<Divider variant="fullWidth" />
<TodoList pagination={{ perPage: 9, page: 1 }} />
...
</PageLayout>
);
};
export default Home;

8. All done.

That's it. You can use this same concept to get data from any API.

Ask the community. #help

If you can't find what you're looking for, the answer might be on our community slack channel. Our team keep a close eye on this and will usually get back to you within a few hours, if not straight away. If you haven't created an account yet please sign up here slack.deity.io.