Forem: getd.io/ - Postman without native apps

💡Reinvent GraphQL using RESTful - Learn GraphQL from the perspective of RESTful in 4 mins.

TechBos😎 — Wed, 25 Sep 2019 15:52:19 +0000

For beginners, GraphQL may seem complex on the surface but it really isn't. This post shows how you can learn core concepts of GraphQL by progressively inventing them in RESTful API.

Let's go back to year 2014. GraphQL isn't a thing yet and our AWESOME-REST-API server has just gone live with a simple RESTful API that returns user name by id:

// A REST API to get user name by user id
GET /user/:id/name
// e.g., get user 123's name
GET /user/123/name
> techbos

One day we decide to also return user's age. So we come up with 4 options:

Option A: create a new endpoint for age

GET /user/123/age
> 23

Option B: merge age with name

GET /user/123/nameAndAge
> { "name": "techbos", "age": 23 }

Option C: return the entire user object and let client pick whichever fields they want

GET /user/123
> { "name": "techbos", "age": 23, "id": 123, "location": "Seattle", ... }

Option D: use query params

GET /user/123?fields=name,age
> { "name": "techbos", "age": 23 }

It's easy to see option A, B, C has its issues:

Option A: Fetching name and age requires client to make two http requests.
Option B: Over time we can end up with hundreds of 'combination' endpoints.
Option C: A lot of wasted bandwidth.

Option D seems reasonable. So we decide to give it a try and improve it as we go:

Use a JSON-like Request Body

Firstly, ?fields=name works fine for simple fields, but gets complicated when we have object/nested fields, e.g., first and last of name object below:

{
  "name": {
    "first": "tech",
    "last": "bos",
  }
}

To solve this, we replace the url query param ?fields= with a JSON-like request body. We also use POST instead of GET.

// Replace ?fields=name,age with request body
POST /user/123
// JSON-like request body for selecting fields
{
  name {
    first
  }
  age
}
// response
> {
    "name": {
      "first": "tech"
    },
    "age": 23
  }

This gives us a clean way of telling server which fields to return. Neat.

Batch Multiple Requests

Next, we notice that our client code always fetches user and posts at same time using two separate requests:

// Get user 123's first name and age
POST /user/123 { name { first }, age }
// Get user 123's post title and content
POST /posts/user/123 { title, content }

Can we do it with only one request? Sure. We can merge them into one single request body, and use a single endpoint /smartql, which stands for 'Smart Query Language':

POST /smartql
// One request body to query for two things
{
  // Replaces /user/123
  user(id: 123) {
    name {
      first
    }
    age
  }
  // Replaces /posts/user/123
  posts(userId: 123) {
    title
    content
  }
}
// response
> {
    "user": {
      "name": {
        "first": "tech"
      },
      "age": 23,
    },
    "notifications": [{
      "title": "Notification 1",
      "content": "Super important",
    }, {
      "title": "Notification 2",
      "content": "Not very important",
    }],
  }

Now we can batch-fetch multiple endpoints in a single request. Neat.

Make API Strong Typed

As our API grows, it becomes more and more difficult for front- and back-end engineers to sync up on the API changes. Our API doc seems always outdated, and it's easy to cause bugs with any API changes.

For example, we change the age field to null-able, and this causes a lot of client-side crashes because the code assumes age to always be valid. To fix this:

First, on the server side, we create a data Schema and use that to make sure any data that goes in or out of our server must follow the expected format. E.g., we can define what fields a User or Post contains, and use a root Query type to define how client can query data using params such as userId.

# Data type for a user
type User {
  name: Name! # non-null!
  age: Int    # nullable
}

# Data type for a user name
type Name {
  first: String
  last: String
}

# Data type for a notification
type Post {
  title: String!
  content: String
}

# Root query type for request body
type Query {
  user(id: Int!): User
  posts(userId: Int!): [Post] # an array of Posts
}

Next, on the client side, we download all the type schemas from server into a schema.smartql file, and use static code checking tools such as TypeScript or Flow to make sure client code follows the schema. For example, if we access user's age without null-checking, or if we query a user object with a string-type id, we will get an error from the type checking.

With this solution we never need to maintain an API doc, as the API itself becomes a living doc.

We are all so very much happy about this new SmartQL. After a year, we decide to open source it under the name of GraphQL because why not. And this is how GraphQL all started...

Just kidding 🙃

I hope this post help you understand the key concepts of GraphQL. You can play with the sample GraphQL queries above in 🏀 getd.io's playground 🏀

If you enjoy this post, please click ❤️ and follow me on twitter @tech_bos!

JSON Web Tokens (JWT) vs. SessionID 🔐 ? explained in 2 mins

TechBos😎 — Tue, 17 Sep 2019 01:34:53 +0000

Just like any other 'tokens', JSON Web Tokens (JWT) is a form of secret that's used for authentication (who you are) and authorization (what you can do). Similarly, a SessionID can also be used for authentication and authorization.

What's the Difference?

The key difference is JWTs are self-contained, while SessionIDs are not.

A JWT contains three parts: <header, payload, signature>. I won't go into details but basically payload contains who the user is and what s/he can do, and signature verifies the token is valid. So when server receives a JWT, it can already retrieve all the information directly from the token, i.e., self-contained.

In contrast, a SessionID is merely a long, unique, random string. By itself there is no user information. When server receives a SessionID, it needs to do extra work to find out which user it belongs to, and then what s/he can do. This extra work often requires a database lookup.

Another way to look at it, is JWT is a driver's license (proves who a user is, and what s/he can do, drive a car), while SessionID is a credit card (simply a random number that links to a bank account, that each transaction requires a card reader to talk to bank).

Why JWT?

The internet has been doing just fine with SessionIDs for many years. Even today, the majority of websites still use SessionIDs. However, in back-end systems that need to handle extremely high volume of http requests, the need to do a database lookup for every single SessionID included in each request can be expensive as it increases latency and reduces throughput.

This is not an issue for JWT as it's all self-contained. The server can simply read the JSON payload from the JWT, without making any database lookups.

Nice! Why not JWT Everything then?

First of all, JWT requires you to properly store and distribute private / public keys that are used for signing and verifying JWTs. And key management is hard to be done right, especially in a large-scale distributed system.

Secondly, since JWTs are self-contained, there is no way to revoke a JWT token. Unlike a SessionID that you can simply delete from the database and thus remove its link to a user, JWTs are not stored in database so once it's created it's valid until expired. It's like credit cards are easy to be replaced, but driver licenses, once issued, are valid anywhere.

Last but not least, because JWTs cannot be revoked, we tend to give them shorter expiration time, which requires users to re-fetch a new JWT more often. There is an option to use refresh tokens but that adds more complexity on the client side, comparing to SessionIDs where the client only needs to store a simple string.

So should I use JWT for my next project?

Probably not. SessionIDs should work just fine :)

[Update] getd.io 🚀 - A free, online REST API builder

TechBos😎 — Thu, 12 Sep 2019 03:52:41 +0000

getd.io is a free, online API builder that I created as Postman without the native apps. Give it a try and let me know what you think. You can also read more in this post.

Since I launched getd.io 🚀 two weeks ago, many changes have made into this product:

New Features

Support for a mobile responsive UI. See the difference here.
Support for new request body formats such as x-www-form-urlencoded and form-data. Read my post if you are unsure what they are.

Support for OAuth2 Bearer token in request headers

The request history uses fuzzy search now.

Usability Improvements

Both the request and response body editor will now automatically switch to the right format (e.g., JSON, raw text, HTML) by detecting the content-type header.

It seems many users who land on the site didn't know what to do. To improve that:

A new landing page was added to show a quick product demo.

A list of sample requests are shown to new users to help them get started.

What's Next

I'm planning on open-sourcing this project. Please leave a comment on this post if you'd like to see this project open sourced, or have suggestions.
I'm building an API explorer as a playground for public APIs. E.g., you can instantly get a token to call Spotify APIs and make it play some music, while at the same time learning how the API works.
I'm planning to build a feature to allow users to create/save workspaces.

Please feel free to leave a comment as I ❤️ feedbacks!

KISS 😘: Keep It Simple & Short - My Tech Writing Principle

TechBos😎 — Wed, 11 Sep 2019 19:04:56 +0000

I'm a true believer of ain't no body got time. So I try very hard to keep my post simple and short (less than 3 mins read). This post shares my approaches to a KISS writing principal.

Break it down, and down

Whenever I find myself writing something longer than 3 minutes, I try to look back and see if I can break it down into multiple posts.

For example, I once came across a post idea of "3 simple ways to improve SEO for your site". But during drafting, I figured the 3 ways mentioned in the post were not tightly related, so I decided to make 3 posts instead, each explaining only one approach.

This way, each of my posts feels more focused, with a cleaner title, and helps readers gain a very specific piece of information in a short amount of time.

Why > How

I prefer talking about why to how. Why? Because there are already too many how-to articles online: how to build an app, how to use an AWS service, etc. But these are ONLY helpful if the reader understands the tech and the concept. And in my opinion there are far less good articles explaining the concepts and contexts around the tech. I was a tech beginner once and I understand how lost I felt when I blindly followed a tutorial without knowing the big picture.

Since I only had 3 mins to explain something, I'd focus on telling the big picture: why the tech existed, where it shines (or not), how it compares to alternatives, and leaving the 'how' part to the readers themselves (or with links).

For example, there are hundreds of online articles talking about how to setup up Babel and Webpack, but after reading many of them I still didn't understand why I needed one or both of them. So I wrote my own:

WTF are Babel and Webpack 😵 ? Explained in 2 mins.

TechBos😎 for getd.io/ - Postman without native apps ・ Sep 8 '19

#beginners #webdev #webpack #babel

Use simple, non-tech words

If you haven't already, please read the What Amazon Says vs. Let's make easier to understand part from this awesome post:

What is AWS? A Guide for Beginners.

Lewis Menelaws ・ May 28 '19

#aws #javascript #productivity #beginners

Kudos to AWS for making it harder to understand their products (aka hiding their cashier)!

Tech posts shouldn't read like a thesis, even when targeting experienced audiences. On the other hand, sometimes even experienced developers don't understand those abstract buzz tech words. Personally, I always find it helpful when concepts are explained in plain words, with real-world examples. This makes the post simple and easy to read. A sample post:

'x-www-form-urlencoded' or 'form-data' 😵 ? Explained in 2 mins.

TechBos😎 for getd.io/ - Postman without native apps ・ Sep 1 '19

#html #javascript #webdev #http

Be Relative

I always feel there is nothing new-new in tech. Almost any 'new' tech, no matter how fancy it seems on the surface, can always be related to some predecessors or alternatives that date years or even decades back.

When explaining a 'new' or 'fancy' tech, it's always helpful to relate or compare to some pre-existing tech that readers are more familiar with. This allows readers to leverage what they already know and link the new concepts on top of it. It also saves me from explaining the concept from scratch, which helps KISS. E.g.,

Webhook is just a fancy way of saying 'event-driven server-to-server API calls' 🤦‍♀️ Explained in 1 min.

TechBos😎 for getd.io/ - Postman without native apps ・ Sep 9 '19

#webdev #webhook #productivity #http

OK I will stop here at the 3-min mark. I love writing KISS posts to help people get excited and learn about tech. Please follow my twitter @tech_bos so you will know when I publish a new post!

Writing is a very subjective topic. To all the awesome writers in dev.to community: What writing principals do you follow? Please share your pro tips in the comment below ❤️❤️❤️

An one-minute fix to make your React site just a bit more Google-friendly 🤝

TechBos😎 — Wed, 11 Sep 2019 03:38:59 +0000

SEO (Search-Engine Optimization) remains important as long as we live in the Google era. Many React apps are written as SPA (Single Page App) and are not Google friendly, as it takes extra effort for Google to render and scrape the front-end Javascript.

Here is an example of how Google indexed my side-project getd.io when it was initially launched. You can see the site description are just some random words from scraping my website's JS:

Btw, a shameless plug: getd.io is a free, online API builder that I created as Postman without the native apps. Give it a try and let me know what you think. You can also read more in this post.

Ideally, we could use SSR (Server-Side Rendering) to help Google get a fully rendered static page, but SSR is tricky and ain't nobody got time for that 😅

To quickly fix this, I used react-helmet to add META tags to getd.io. Then, I went to Google Search Console and requested a re-index. After that, the search result looked much better:

And here is what my code looks like:

const seo = {
  title: "getd.io/",
  description:
    "A free, online API builder that works with CORS. A Postman alternative without the need for client app installation.",
  url: "https://getd.io/",
  image: "https://getd.io/image.png"
};

<Helmet
  title={seo.title}
  meta={[
    {
      name: "description",
      property: "og:description",
      content: seo.description
    },
    { property: "og:title", content: seo.title },
    { property: "og:url", content: seo.url },
    { property: "og:image", content: seo.image },
    { property: "og:image:type", content: "image/png" },
    { property: "twitter:image:src", content: seo.image },
    { property: "twitter:title", content: seo.title },
    { property: "twitter:description", content: seo.description }
  ]}
/>

You can put <Helmet> component anywhere in your React tree, and they will be properly moved to under <head>:

Webhook is just a fancy way of saying 'event-driven server-to-server API calls' 🤦‍♀️ Explained in 1 min.

TechBos😎 — Mon, 09 Sep 2019 07:28:41 +0000

There is nothing new here. I could've ended my post right here because the title pretty much says it all. But I do want to shamelessly plug-in my side-project below so please read on.

We are all very familiar with how client-to-server API calls work. Yeah, I'm talking about those GET, POST, PUT http requests.

By the way, you can play with all kinds of API requests in getd.io that I created. It's a web-based Postman without native apps. Let me know what you think ❤️

Instead of client-to-server, webhooks are server-to-server API calls. Yeah, I'm talking about the same old GET, POST, PUT http requests, like above. But, the key difference is, since these calls are sent from a machine (server), they need to be triggered by events, aka hooks.

A common webhook example is, whenever a new commit is pushed to your Github repo, it triggers Github to make a call to your Jenkins server so it starts building the new code. Here we have a 'push-event driven Github-to-Jenkins API call'.

In this case Github will provide a JSON payload to Jenkins with all information about this new commit.

So next time you see some server uses webhooks, it simply means it can be triggered by some events to send some http request (API call) to another server.

WTF are Babel and Webpack 😵 ? Explained in 2 mins.

TechBos😎 — Sun, 08 Sep 2019 00:58:50 +0000

Babel and Webpack are apple🍎 and banana🍌. One never compares them side-by-side as they solve different problems. This post explains their different concepts.

Babel

Babel is simply a translator, who translates your 'fancy' (ES6+) JS code into 'not-so-fancy' (ES5) ones that browser (front-end) or Node.js (back-end) understands.

Why we speak fancier than browser and Node.js? Because we can't wait to use the latest and greatest, even before they are officially supported.

Below is a fancy code that most developers write today. Despite of how fancy it is, our browser / Node.js has no idea what it's talking about. (Note: Some Node.js higher versions have ES6 support now.)

// ES6 syntax
import moment from 'moment';

export default () => moment().format("YYYY Do MM");

And this is why we need Babel to translate above into the equivalent not-so-fancy code below, that our browser / Node.js actually understands.

// ES5 syntax
const moment = require('moment')

function getDateString() {
  const date = moment();
  return date.format("YYYY Do MM");
}

exports.default = getDateString;

That's why Babel is sometimes called a transpiler.

It's worth noting that Babel is commonly used for both front- and back-end. Why do I mention this? Because Webpack is front-end only (in most cases).

Webpack

If Babel is a translator for JS, you can think of Webpack as a mega-multi-translator that works with all kinds of languages (or assets). For example, Webpack often runs Babel as one of its jobs. Another example, Webpack can collect all your inline CSS styles in your Javascript files and bundle them into one.

Why do we need such a monster for front-end, but not back-end?

Because front-end has many kinds of assets such as CSS, SASS, images, fonts and is way more complex and dynamic than back-end which only has JS. And in the end of day we need to somehow package all variety of assets into a small file that our users' browser can download at page load time. This is also known as minify and uglify. You see, back-end has none of the above requirement.

Another important reason is that front-end doesn't work with modules (again, in most cases). Modules are built-in features of Node.js, not browsers. Nowadays developers are so used to npm install, import and export JS modules in front-end, as it allows us to better organize code and share packages. But in reality they are only syntactic sugars, and it's Webpack's job to figure out all the dependencies among all the modules that we use in the code, and compile them into one big chunk of JS code that the browser actually understands.

When do we use Webpack in back-end? A good use case is to support SSR (Server-Side Rendering).

To sum up,

Backend: we use Babel so that we can use the fanciest JS syntax (ES6/7) with Node.js.
Frontend: we use Webpack (which uses Babel and other things) to compile JS code and many other assets into a few small bundle files that our users can download when they first load our webpage. For example, create-react-app uses Webpack and Babel when creating your app.

How to manage secrets and configs using dotenv in Node.js and Docker

TechBos😎 — Sat, 07 Sep 2019 16:16:15 +0000

What is `dotenv`?

It's a javascript package that reads KEY=VALUE from a .env file (example below) and sets each pair as env variables.

// 1. Create a .env file:
DB_ADMIN_USERNAME=techbos
DB_ADMIN_PASSWORD=Pa$$w0rd

// 2. In your node app, load dotenv to read .env and set env variables when app starts
require('dotenv').config();

// 3. You can now use the env variables in your app
connectDatabase({
  username: process.env.DB_ADMIN_USERNAME, //techbos
  password: process.env.DB_ADMIN_PASSWORD, // Pa$$w0rd
});

Why should I use `dotenv`?

dotenv allows you to separate secrets from your source code. This is useful in a collaborative environment (e.g., work, or open source) where you may not want to share your database login credentials with other people. Instead, you can share the source code while allowing other people to create their own .env file.

It's also useful for dynamically configure your app without changing the source code. For example, you can set DB_URL to a dev database for local development. Or, if you want to print logs to console for local development, but not in prod, you can do:

// .env file
ENV=dev

// in your app
if (process.env.ENV === 'dev') console.log(...);

For real-world applications that are deployed to hundreds or even thousands of instances, using dotenv (or use other similar tech) allows all instances to share the same source code, while each having a different .env file so they can use different configurations, e.g., connecting to different databases or writing logs to different endpoints.

How to setup `dotenv` in my project?

1. Preload `dotenv` in node.js

Start your node app with dotenv preloaded so you don't even need to require dotenv in your source code.

// use this
node -r dotenv/config index.js
// instead of
require('dotenv').config();

2. Add `.env` to `.gitignore`

You should never share .env file in source control. Instead, create a separate private repo to store your own .env files, while sharing the rest of the source code with others.

//.gitignore
.env

3. Create as many `.env` as you like

It's typical to have multiple .env files. E.g., you may have one for dev, one for stage and one for prod. After you checkout the source code, copy over the .env file for your environment and start the app.

3. Start your app

// E.g., use with babel-node for local development
nodemon --exec babel-node -r node_modules/dotenv/config src/index.js
// E.g., run with node in production
node -r dotenv/config src/index.js

4. Run in docker

// Dockerfile
CMD node -r dotenv/config ./build/index.js

Use `dotenv-safe`

A good alternative to dotenv is dotenv-safe, which is identical to dotenv except that it allows you to create a .env.example file. This serves two purposes:

It allows you to specify all required env variables in the example file. At runtime the package checks if a .env file has all the required variables defined, and throws if not.
You can share the .env.example file with others so everyone knows what env variables are required.

Use in Docker

In some cases, building the .env file into a docker image is considered a bad practice because if the image is shared with others, the secrets can be leaked.

To fix that, you can map a .env file into docker at runtime:

volumes:
  - /local/file/path/to/.env:/app/.env

Another approach is to use the env_file docker option. You can read more here

Http Cookies 🍪 is a 25-year-old simple string store. Explained in 3 mins.

TechBos😎 — Fri, 06 Sep 2019 18:38:54 +0000

I ❤️ cookies. They have been around since 1994. The world of Inter-web today would look very different if we didn't have cookies.

Without cookies, the web would be a static and boring place, where everybody would be reading the same news feed on dev.to.

In fact, this post wouldn't even get published if not because of cookies.

So, what are Cookies?

Cookies are simple key-value data that your browser stores. E.g., This line below is a cookie.

sessionId=123

A cookie can be created/updated/deleted by

Your browser via Javascript code document.cookie, or
The server via set-cookie response headers

But, cookies are private to domain, meaning only the client-side code running in the domain can access it. E.g., when you open twitter.com in browser, its javascript cannot see the cookie below.

// This cookie is only accessible by dev.to's javascript when running on the browser
sessionId=123; domain="dev.to";

The browser automatically sends all cookies of a domain as part of the requests to the domain's server. E.g., with the example above, each request to dev.to will include that cookie. This allows dev.to's server to read the cookie value from the request, and associate the request with a previous visitor (aka session).

Just like any cookies 🍪 you can buy in stores. They expire.

// expires at time
sessionId=123; expires=Thur, 5 Sep 2019 12:34:56 UTC
// expires in a year
sessionId=123; max-age=31536000
// expires when browser closes
sessionId=123;

Sometimes there are too many cookies to send for a certain domain, and we can use path to send only cookies that match a path.

// only send this cookie when current location is "/newsfeed/*"
sessionId=123; path="/newsfeed"

Why Cookies rock?

Though invisible to most users, it's most famous for supporting sessionIds (or similar names), which is a fundamental building block for enabling user-identity on web.

Taking dev.to as an example. First time I accessed dev.to, their server set a cookie with name _PracticalDeveloper_session to my browser. Since then, every time I go to dev.to, I present the _PracticalDeveloper_session cookie value in each http request to their server, and that proves me as techbos. This allows dev.to server to send me MY personal newsfeed and notifications, not @ben's.

See my dev.to cookies in image below:

What are Cookies not so great for?

First of all, you can't eat them 🙃 .

Besides that, cookies are bad for storing arbitrary data in the browser, because:

It has some serious size limitations (see bottom).
They are automatically included in every single request sent to the server. The more data in cookies, the more bandwidth your request will consume.

What are Alternatives to Cookies?

For supporting sessionIds, there is no alternatives to cookies in web's world.

For storing data in the local browser, there are three choices:

LocalStorage: persisted until user clears cache.
Session Storage: persisted until browser or tab is closed.
IndexedDB: Useful for storing large amount of structured data. Pretty complex low-level stuff.

However, do NOT store sensitive information (e.g., tokens, passwords, etc.) using above options as they are not meant as secure data stores.

Don't touch my Cookies!

The TL;DR version is to use Secure and HttpOnly to protect your cookies.

sessionId=123; Secure; HttpOnly;

Secure ensures the cookie is only available to server when accessing the site using https. Thus preventing man-in-the-middle.

HttpOnly ensures the cookie is NOT accessible by javascript. Thus preventing XSS (cross-site scripting), aka bad guy running their smelly js on your webpage.

How big a Cookie can I make?

Each browser has slightly different implementation over how many cookies per domain can be stored at a time, and what the max data size for each cookie. A general rule of thumb is each cookie shouldn't exceed 4KB of data, and the total size of all cookies for one domain shouldn't exceed 4KB either.

🆘 Open sourcing getd.io

TechBos😎 — Fri, 06 Sep 2019 17:31:19 +0000

I'm planning to open source getd.io 🚀, a free and online REST API builder that I built weeks back. You can read more about it in this post.

While being super excited 😍 , as someone who has never open sourced anything in my life, I also want to make sure the project is in a good shape before it goes open source.

The front-end is trivial so I think open-sourcing it would be as simple as opening up code access in github. The back-end, however, is a bit tricky that I could really use some help from the awesome dev.to community ❤️ on open-source best practices.

For viewers who didn't know getd.io, the unique feature of this project, comparing to other Postman alternatives, is that it uses a back-end server as a proxy to send and receive API requests, thus bypassing CORS (Cross-Origin Resource Sharing) restrictions on the browsers. I also plan to add more features such as:

Create and save personal/team workspaces.
An API explorer to share and play other people/company's public APIs, e.g., Spotify APIs, or Twitter APIs.
and more...

As you can quickly tell, the backend has a bit of complexity around user auth, database, and other things. So my list of questions follows:

API Keys

Update: I did some research and answered this part of the questions in this post

I have (and will have) several API keys for this project. E.g., there is a Github API key for user sign-ins. There will be API keys for services such as Spotify for users to try out Spotify APIs. Currently these keys are stored in a version-controlled json and read via the config npm package at runtime. Questions:

What's the best practice to move these keys out of my repo, but still feed them at runtime? E.g., use ENV + docker-compose? Should I put the keys in a private repo?
Is there a way to share some development API keys (probably a bad idea) so contributors won't have to go through the hassle of applying and managing their own keys?

Database

The project uses mongoDB. For local dev, it uses a free-tier mongoDB from Atlas. For prod, it uses a docker mongo running on my server. Questions:

Is it common to ask contributors to set up their own mongoDB for developing on the repo?
I figure sharing a dev mongoDB instance would be a terrible idea, because people will see other people's tokens. But is there a way for sharing a dev mongoDB so contributors won't have to set up their own?

License

I heard MIT are gud. Any other suggestions?

Lastly,

Just in general:

What are some pro-tips for first-time open-source creator (me)?
Is it a good idea to open source a project that still has many pending features that need design, or should I hold until the project is more mature?
How to make contributor's life easier so they can focus on coding, not spending hours setting up environments?
How to collaborate with contributors on features, especially complex ones? E.g., the feature of 'creating personal workspaces' would involve many complex database schemas, API schemas, UIs, etc. How does that work?

Thank you in advance! I can't wait to open source getd.io and see awesome things happen! 🎉🎉🎉

Should you useState or useReducer 🤷? Doesn't matter really. Explained in 3 mins.

TechBos😎 — Wed, 04 Sep 2019 15:24:22 +0000

The React doc recommends useReducer for handling complex state values. But to me they are equally powerful. Let me show you how.

useReducer can replace useState

First, the simpler case: any useState can be implemented using useReducer. In fact, the useState hook itself is implemented by a reducer.

Let's create a simple React state with useState. The state contains a count number.

type State = { count: number };

const [state, setState] = React.useState<State>({ count: 0 });

We can re-implement the same with useReducer.

type Action = {
  type: 'COUNT_CHANGED',
  count: number,
};

const reducer: React.Reducer<State, Action> = (
  prevState: State,
  action: Action
): State => {
  switch (action.type) {
    case "COUNT_CHANGED":
      return { ...prevState, count: action.count };
  }
};

const [state, dispatch] = React.useReducer(reducer, { count: 0 });

Except for more lines of code, they function exactly the same.

Here useReducer takes in two parameters.

The first being a reducer function: (prevState, action) => newState. Upon dispatching an action, it updates (reduces) the prevState to a newState.
The second is the initial state, same to the one passed into useState.

We have only one action called COUNT_CHANGED. So the following two lines will trigger the same state update:

// with useState
setState({ count: 1 });

// with useReducer
dispatch({ type: 'COUNT_CHANGED', count: 1 });

useState can replace useReducer, too

One claimed advantage of useReducer is its ability to handle complex state values. Let's create an example here. Let's say we have a root-level form component that contains three input components, and we want each input to handle its own value. The UI looks like below:

    <UserForm>
      <FirstNameInput />
      <LastNameInput />
      <AgeInput />
    </UserForm>

We create a reducer below to handle 3 input values:

// A complex state with user name and age
type UserState = {
  name: {
    first: string,
    last: string,
  },
  age: number,
};

// Three action types to update each state value
type Action =
  | {
      type: "FIRST_NAME_CHANGED";
      first: string;
    }
  | {
      type: "LAST_NAME_CHANGED";
      last: string;
    }
  | {
      type: "AGE_CHANGED";
      age: number;
    };


const reducer: React.Reducer<UserState, Action> = (
  prevState: UserState,
  action: Action
): UserState => {
  switch (action.type) {
    case "FIRST_NAME_CHANGED":
      return { ...prevState, name: { ...prevState.name, first: action.first } };
    case "LAST_NAME_CHANGED":
      return { ...prevState, name: { ...prevState.name, last: action.last } };
    case "AGE_CHANGED":
      return { ...prevState, age: action.age };
  }
};

And now use it in our UserForm component. Note that dispatch is passed into each Input so they can trigger actions to update their own field.

const UserForm = () => {
  const [state, dispatch] = React.useReducer(reducer, {
    name: { first: "first", last: "last" },
    age: 40
  });
  return (
    <React.Fragment>
      <FirstNameInput value={state.name.first} dispatch={dispatch} />
      <LastNameInput value={state.name.last} dispatch={dispatch} />
      <AgeInput value={state.age} dispatch={dispatch} />
    </React.Fragment>
  )
}

Done. This is how useReducer can work for complex states. Now how to convert to useState?

A naive way is passing down one big state object to each Input. We have to pass down the entire state because each Input needs to know the 'full picture' of current state for it to properly construct a new state. Something like below:

// This is a bad example.
const UserForm = () => {
  const [state, setState] = React.useState({
    name: { first: "first", last: "last" },
    age: 40
  });
  return (
    <React.Fragment>
      <FirstNameInput state={state} setState={setState} />
      <LastNameInput state={state} setState={setState} />
      <AgeInput state={state} setState={setState} />
    </React.Fragment>
  )
}

This is bad for several reasons:

No separation of duties: Each Input now requires full state as its props to work. Making it harder to refactor and unit test.
Poor performance: Any state change will trigger all Inputs to re-render.

In fact, these are exactly the reasons why React team suggests using useReducer for this kind of complex state.

But that doesn't mean we can't use useState to achieve the same result. It just requires a bit more crafting.

function Counter() {
  const { state, setFirstName, setLastName, setAge } = useComplexState({
    name: { first: "first", last: "last" },
    age: 40
  });
  return (
    <React.Fragment>
      <FirstNameInput value={state.name.first} setFirstName={setFirstName} />
      <LastNameInput value={state.name.last} setLastName={setLastName} />
      <AgeInput value={state.age} setAge={setAge} />
    </React.Fragment>
  )
}

// A custom hook that returns setter functions for each field.
// This is similar to what the reducer above is doing,
// we simply convert each action into its own setter function.
function useComplexState(initialState: UserState): any {
  const [state, setState] = React.useState<UserState>(initialState);
  const setFirstName = first =>
    setState(prevState => ({
      ...prevState,
      name: { ...prevState.name, first }
    }));
  const setLastName = last =>
    setState(prevState => ({
      ...prevState,
      name: { ...prevState.name, last }
    }));
  const setAge = age => setState(prevState => ({ ...prevState, age }));
  return { state, setFirstName, setLastName, setAge };
}

In fact, we can completely rewrite useReducer with only useState:

const useReducerImplementedByUseState = (reducer, initialState) => {
  const [state, setState] = React.useState<State>(initialState);
  const dispatch = (action: Action) => setState(prevState => reducer(prevState, action));
  return [state, dispatch];
};

// above implementation
const [state, dispatch] = useReducerImplementedByUseState(reducer, initialState);
// is same with
const [state, dispatch] = useReducer(reducer, initialState);

In conclusion,

For simple value state, do useState for it uses less lines.
For complex state, use whichever you feel like at the moment 🤪

Do you prefer useState or useReducer in your projects? Share your thoughts in the comment below ❤️

Thinking in Java: Learn React and React Hooks with Java Code ☕

TechBos😎 — Tue, 03 Sep 2019 22:57:24 +0000

As a long-time Java developer, it took me a while to understand some of the magics behind React. This post is my attempt to explain some of them in Java concepts. It's not meant to provide a strict mapping from Java to React.

Below is a React Counter component. It renders a count number, with a button to increment it. Every time the button is clicked, the count is added by one and the value is updated on the screen.

type Props = { initialCount: number };
type State = { currentCount: number };

class Counter extends React.Component<Props, State> {
  // Sets currentCount to initialCount when component is created
  state: State = { currentCount: this.props.initialCount };

  // Renders a text and a button, which increments count by one when clicked.
  render() {
    return (
      <div>
        {this.state.currentCount}
        <button onClick={() =>
          this.setState({ currentCount: this.state.currentCount + 1 })
        }>
          Increment
        </button>
      </div>
    );
  }
}

// Renders Counter at root
const rootElement = document.getElementById("root");
render(<Counter initialCount={0} />, rootElement);

The same React component can be (sort-of) written in Java:

// The Props class to pass data into Counter, publicly construct-able.
public class Props {
  public final int initialCount;
  public Props(int initialCount) { this.initialCount = initialCount; }
}

public class Counter {
  // The State class to hold internal data of Counter, private only.
  private static class State {
    final int currentCount;
    State(int count) { this.currentCount = count; }
  }

  private State state;
  private Props props;
  private boolean shouldRender;

  // Constructor. Called once per component lifecycle.
  public Counter(final Props props) {
    this.updateProps(props);
    this.setState(new State(props.initialCount));
  }

  // Called by external whenever props have changed.
  public void updateProps(final Props props) {
    this.props = new Props(props.initialCount);
    this.shouldRender = true;
  }

  // Internal state update method for current count.
  private void setState(final State newState) {
    this.state = newState;
    this.shouldRender = true;
  }

  // Only allows render when shouldRender is true, i.e., props or state changed.
  public boolean shouldRender() {
    return this.shouldRender;
  }

  // Returns a 'virtal DOM' node 'Div' that contains a 'Text' node and a 'Button',
  // which increments count by one when clicked.
  public ReactNode render() {
    this.shouldRender = false;
    return new Div(
      new Text(this.state.currentCount),
      new Button("Increment", new OnClickHandler() {
        @Override
        public void onClick() {
          setState(new State(state.currentCount + 1));
        }
      });
    );
  }
}

// Renders Counter at root
public static void renderAt(HTMLElement root) {
  Counter counter = new Counter(new Props(0));
  root.addChild(counter);
  if (counter.shouldRender()) {
    counter.render();
  }
  ...
}

To readers who have a Java background, table below maps some core React concepts into Java ones.

React Concept	Java Concept
`component`	`class`
`props`	Passed-in `parameters` of constructor or `updateProps()` method, immutable internally
`state`	A set of all `private variables`, immutable internally
`setState()`	Replaces the previous group of private variables with a new group
`render()`	Creates a new view with values applied

A few interesting things to note here:

`props` vs. `state`

In React, props are used for external world to communicate with the component, similar to Java constructor and public method parameters. In example above, it's used for setting its initial count value.

state, on the other hand, is used by the component internally, holding data that only matters to the component itself. This is similar to private variables in Java. However, a parent component's state can become a child component's props. E.g., Counter's currentCount is passed into Text component as the latter's props.

Both props and state should be immutables internally. In React, we never change their internal values directly. Instead, pass in a new props to the component (example below), and use setState() for setting a new state. Note how they are internally final in Java code above.

No Change, No Render

React only renders the component if either props or state has changed. This allows it to avoid unnecessary DOM updates. In above example, the component doesn't re-render until either button is clicked (a state change) or initialCount is changed (a props change). This is simulated using shouldRender() method above.

Virtual DOM nodes

render() returns virtual nodes. They are objects that describes how a certain type of UI should be rendered. They are not the end results. It's up to the React engine to decide how UI will be generated and presented on the screen. This allows React to work with different platforms. E.g., React.js renders a Html <button> while React Native renders an Android Button or iOS UIButton.

Handle `props` Changes

Now, let's briefly talk about React lifecycles. React provides several lifecycle methods. Today we take a look at componentDidUpdate().

Let's say we want the component to reset state.currentCount if the passed-in props.initialCount has changed. We can implement componentDidUpdate() as below:

class Counter extends React.Component<Props, State> {
  state: State = { currentCount: this.props.initialCount };

  // After props changed, check if initialCount has changed, then reset currentCount to the new initialCount.
  componentDidUpdate(prevProps: Props) {
    if (prevProps.initialCount !== this.props.initialCount) {
      this.setState({ currentCount: this.props.initialCount });
    }
  }

  render() {
    ...
  }
}

This may be written in Java as:

class Counter {
  ...
  // Called by external whenever props have changed.
  public void updateProps(final Props props) {
    final Props prevProps = this.props;
    this.props = new Props(props.initialCount);
    this.shouldRender = true;
    this.componentDidUpdate(prevProps);
  }

  private void componentDidUpdate(final Props prevProps) {
    if (prevProps.initialCount != this.props.initialCount) {
      setState(new State(this.props.initialCount));
    }
  }
  ...
}
Counter counter = new Counter(new Props(0));
counter.updateProps(new Props(100));

The external world calls updateProps() to update Counter's props. Here, updateProps() preserves prevProps, and passes it into componentDidUpdate(). This allows the component to detect a props change and make updates accordingly.

Also note that setting new props doesn't require creating a new component instance. In the example above, the same Counter component is reused with new props. In fact, React tries to reuse existing components as much as possible using some smart DOM matching and the key props. It only creates new components when they cannot be found on the current DOM tree.

React Hooks

If you are learning React, you must learn Hooks as it's the new standard (a good thing). Let's quickly look at the equivalent code in React Hooks:

const Counter = ({ initialCount }: Props) => {
  const [currentCount, setCurrentCount] = React.useState(initialCount);

  React.useEffect(() => {
    setCurrentCount(initialCount);
  }, [initialCount]);

  return (
    <div>
      {currentCount}
      <button onClick={() => setCurrentCount(currentCount + 1)}>
        Increment
      </button>
    </div>
  );
};

The code is just much conciser because many things are hidden behind each line.

The line below uses React.useState(). It kills two birds with one stone (sorry, birds 🥺).

  const [currentCount, setCurrentCount] = React.useState(initialCount);

It sets state.currentCount as initialCount similar to the Java constructor, and
returns a setCurrentCount() function that's equivalent to the setState() method used in Java.

The benefit of using this pattern is that you can break down one single state object into multiple simple values, each controlled by its own useState() method.

Next, the lines below uses React.useEffect() to create an effect, which is run every time the component updates.

  React.useEffect(() => {
    setCurrentCount(initialCount);
  }, [initialCount]);

In this case, the effect is tied to the initialCount value (note the last parameter of useEffect()). This tells useEffect to only run setCurrentCount(initialCount) when initialCount changes. This is equivalent to Java code below:

  private void componentDidUpdate(final Props prevProps) {
    if (prevProps.initialCount != this.props.initialCount) {
      setState(new State(this.props.initialCount));
    }
  }

There are many other magics in React and Hooks that go beyond this post. Leave a comment below if you'd like to learn more on this topic ❤️❤️❤️

Forem: getd.io/ - Postman without native apps

💡Reinvent GraphQL using RESTful - Learn GraphQL from the perspective of RESTful in 4 mins.

Use a JSON-like Request Body

Batch Multiple Requests

Make API Strong Typed

JSON Web Tokens (JWT) vs. SessionID 🔐 ? explained in 2 mins

What's the Difference?

Why JWT?

Nice! Why not JWT Everything then?

So should I use JWT for my next project?

[Update] getd.io 🚀 - A free, online REST API builder

New Features

Usability Improvements

What's Next

KISS 😘: Keep It Simple & *Short* - My Tech Writing Principle

Break it down, and down

Why > How

WTF are Babel and Webpack 😵 ? Explained in 2 mins.

TechBos😎 for getd.io/ - Postman without native apps ・ Sep 8 '19

Use simple, non-tech words

What is AWS? A Guide for Beginners.

Lewis Menelaws ・ May 28 '19

'x-www-form-urlencoded' or 'form-data' 😵 ? Explained in 2 mins.

TechBos😎 for getd.io/ - Postman without native apps ・ Sep 1 '19

Be Relative

Webhook is just a fancy way of saying 'event-driven server-to-server API calls' 🤦‍♀️ Explained in 1 min.

TechBos😎 for getd.io/ - Postman without native apps ・ Sep 9 '19

An one-minute fix to make your React site just a bit more Google-friendly 🤝

Webhook is just a fancy way of saying 'event-driven server-to-server API calls' 🤦‍♀️ Explained in 1 min.

WTF are Babel and Webpack 😵 ? Explained in 2 mins.

Babel

Webpack

To sum up,

How to manage secrets and configs using dotenv in Node.js and Docker

What is dotenv?

Why should I use dotenv?

How to setup dotenv in my project?

1. Preload dotenv in node.js

2. Add .env to .gitignore

3. Create as many .env as you like

3. Start your app

4. Run in docker

Use dotenv-safe

Use in Docker

Http Cookies 🍪 is a 25-year-old simple string store. Explained in 3 mins.

So, what are Cookies?

Why Cookies rock?

What are Cookies not so great for?

What are Alternatives to Cookies?

Don't touch my Cookies!

How big a Cookie can I make?

🆘 Open sourcing getd.io

API Keys

Database

License

Lastly,

Should you useState or useReducer 🤷? Doesn't matter really. Explained in 3 mins.

useReducer can replace useState

useState can replace useReducer, too

Thinking in Java: Learn React and React Hooks with Java Code ☕

props vs. state

No Change, No Render

Virtual DOM nodes

Handle props Changes

React Hooks

KISS 😘: Keep It Simple & Short - My Tech Writing Principle

What is `dotenv`?

Why should I use `dotenv`?

How to setup `dotenv` in my project?

1. Preload `dotenv` in node.js

2. Add `.env` to `.gitignore`

3. Create as many `.env` as you like

Use `dotenv-safe`

`props` vs. `state`

Handle `props` Changes