DEV Community: 🅖🅡🅔🅖🅞🅡🅨 🅞🅡🅣🅞🅝

Naming things is difficult...

🅖🅡🅔🅖🅞🅡🅨 🅞🅡🅣🅞🅝 — Fri, 18 Jun 2021 08:39:14 +0000

I was recently asked to write a section for our company's new developer handbook on API design...

Top to bottom.... here we go...

You might have seen in the wild, a request like this:

/api/v2/customers/24/orders/1

/products/56/variants

Both of these examples are pretty sound design choices, and here's why:

Prefixing

It's a good idea to start the API routes with a prefix signalling that this path is indeed an API. It instantly warns developers that the end points are unlikely to return a human readable response out of the box...

So... /api all the way.

Unless you've got a subdomain, like https://api.mydomain.com where this becomes more redundant...

Versioning

If you're designing a greenfield API, that is, no existing legacy API to write over, or replace, then it's a good idea to start with the idea that your brand new API might be replaced some day

In order to do that, one approach is to 'version' or 'namespace' the API. In this way, clients consuming the API (front-ends, data-only clients) can easily configure themselves to work against any specified / working version of the API and know what to get...

Need to deprecate a method? New version
Need to make a breaking change to shape of data response? New version
Need to modify the parameters that an API accepts? New Version

/api/v1 or /api/v2/ and so on...

RESTful resources

REST APIs (aka representational state transfer) APIs are of course not the ONLY way of defining an API, we've got SOAP/XML, RPC, and many many other protocols...

REST is also more of a concept and protocol that an API should conform to, than a hard and fast set of rules, but they make a lot of sense and are very easy to reason about

HTTP methods

The first thing to consider is to design our API in terms of the 5 most common HTTP methods: GET, POST, PUT, PATCH, DELETE

GET for reading/viewing/listing
POST for creating (*)
PUT for creating /replacing (*)
PATCH for updating
DELETE well...

(* explained later)

The important thing to note is a GET request should invariably never have side effects -- that is it shouldn't change the state of a resource... talking of resources...

Designing for resources / entities

The next big thing is that we're usually going to be designing the API against a bunch of entities that we've designed in our back-end... for example Users or Customers or Orders etc.

Some of these resources might be embedded in each other, and some might be stand-alone, but via convention we should be able to address this...

URL format

A note about entity naming in URLS: Every programming language is different, they use CapitalCase, camelCase, kebab-case, snake_case, etc. A URL is not a programming language, stick to kebab-case - URLS are case insensitive and you enhance readability by exposing the idiosyncrasies of your back-end language to your user!

Fetching multiple resources:

The entity should be pluralised and be the first item in the path

GET /api/v1/customers
GET /api/v1/users
GET /api/v1/orders

Sometimes these resources required pagination and in almost all cases, the GET request should expect this to be done via query strings

GET /api/v1/customers?page=1&page_size=20

Fetching single resources:

The same path as before, with a unique ID appended in the path:

GET /api/v1/customers/12
GET /api/v1/users/1
GET /api/v1/orders/24

It's almost always preferred to use integer IDs over string IDs in a SQL-based or RDBM system. (Don't get tied u over this, though, it's beyond the scope of this article)

You might want to allow (via parameters) restricting the information that comes back about a single entity... again, query strings (not a request body)

GET /api/v1/customers/1?fields=id,firstname,lastname

Creating a resource:

POST/PUT are the two choices here. If we're being strict with REST definitions, then POST is for creating without regard to idempotency (idempotency is the idea that a repeat operation like create should only happen once even with repeated calls) and PUT should be used for replacing or updating a resource, or you're creating with an expected ID or unique identifier.

Obvioulsy parameters go in the BODY as application/json or application/url-form-encoded or whatever you require

Either way, they should be name with the pluralised endpoint:

POST /api/v1/customers
- response: 201 { "id": 12, "name": ... }
PUT /api/v1/customers/1
- response: 200 { "id": 1, "name": ... }

Updating a resource:

Updating can be done with PUT (see above) or PATCH. PATCH is usually reserved for partial updates of a resource. DELETE is well, for removing a resource

Naming: same as above - use the pluralised endpoint + a unique identifier.

PUT /api/v1/customers/1
- response: 200 { "id": 12, "name": ... }
PATCH /api/v1/customers/1
- response: 200 { "id": 1, "name": ... }
DELETE /api/v1/customers/1
- response: 200

Nested resources:

Ok, gets a bit tricky, but in general the same rules are just re-used going on down the tree!

A Customer might have Orders or Bussiness Units or even a single one-to-one attribute like Address

GET /api/v1/customers/1/orders
GET /api/v1/customers/1/orders/1
POST /api/v1/customers/1/orders
GET /api/v1/customers/1/business-units
GET /api/v1/customers/1/address

Authentication

Don't put your API keys in query strings, folks! It's just bad practice. An authentication request is full of side effects. POST it! And put it in the request body, these things can show up in browser histories and server logs and are a big no no!

POST /api/v1/auth/login

{
  "username": "...",
  "password": "..."
}

Final thoughts

All in all, there's generally very little reason to name a resource in a URL in the singular unless it's an embedded entity as mentioned above (Address), or when the resource cant really be pluralised (hello Advice or Evidence)

Otherwise, it's a spelling mistake, and you should be ashamed of yourself. (Only joking...)

Merge two arrays as a set

🅖🅡🅔🅖🅞🅡🅨 🅞🅡🅣🅞🅝 — Tue, 08 Dec 2020 08:51:09 +0000

So, I love the idea of using mathematical set theory in my programming. Specifically, I really want to make use of Javascript's recent addition Set for the convenience of guaranteeing non-duplicate values and convenience APIs for iterating:

Example

const s = new Set([
  1,
  2,
  3
])

s.add(3) // 1, 2, 3
s.has(3) // true
s.forEach(...) // etc

Problem is, it only works with primitives: e.g. Number, String and not arrays or objects due to (referential) equality limitations in JS (e.g. { a: 1 } !== { a: 1 }.

Which is kinda annoying.

So I wrote functional utility to add an arbitrary array of objects to an existing array, using a specific prop. My thoughts are: is this the most efficient way to do it? What better ways are there to do this?

This is O(n^2) which isn't exactly desirable?

const mergeArraysAsSet = (ex, merge, compareProp = 'id') => {
  return ex.concat(
    merge.reduce((mergeArray, next) => {
      if (!ex.find((x) => x[compareProp] === next[compareProp])) {
        mergeArray.push(next)
      }
      return mergeArray
    }, [])
  )
}

Where to go for icons -redux

🅖🅡🅔🅖🅞🅡🅨 🅞🅡🅣🅞🅝 — Mon, 30 Nov 2020 13:51:26 +0000

Inspired by this post （https://dev.to/jolouie7/my-favorite-place-to-look-for-icons-5dh) I felt you should all really be informed about The Noun Project. If you don’t already - TNP is a repository of thousands of custom, hand crafted icons in SVG/PNG format that can completely transform a design.

If you don’t already know it, check out it out. It’s better than anything you’ve ever used: https://www.thenounproject.com/

Canvas Paintball Gun

🅖🅡🅔🅖🅞🅡🅨 🅞🅡🅣🅞🅝 — Thu, 17 Sep 2020 08:39:48 +0000

I had fun making this. It's a prototype for the new service I'm working on. Enjoy.

How not to get people to use your library

🅖🅡🅔🅖🅞🅡🅨 🅞🅡🅣🅞🅝 — Wed, 05 Aug 2020 14:26:16 +0000

PREFACE: I want to point out that in writing this article by saying, I'm not trying to be vindictive or to spite, but to draw attention to how not to behave as an open source developer.

The only real option

Recently, I've been working on an app in React Native, in which I needed to write a share extension in iOS and Android. Like any good developer, I'm aware that I'm standing on the shoulders of giants, and in all likelihood, someone had the same problem and solved it, well before I came along. So, after an afternoon Googling for a solution, it became apparent the only real working solution for React Native share extensions was a library (in a case of extreme nominative determinism) aptly called react-native-share-extension.

Unloved, broken, despairing

The only problem is that this lib seems to have been abandoned. The maintainer has long since stopped maintaining the package and it's accumulating issues at a fair lick, with reports of it breaking in the latest version (0.6.2 at time of writing) of React Native.

At first as you look through the issues, you see lots of people replying, reporting similar experiences, trying to help, offering solutions, or in some cases, recommending other libraries. Like this helpful comment:

Initially, I thought this might be useful: 'this is just being helpful', and I checked it the repo, but soon I realised his solution doesn't really do what I need it to. So I'm looking at other issues, trying to gauge if this is really the lib I want to use. And it's then that I started seeing a worrying pattern...

So spammy I could make a sandwich

It becomes apparent spanning back over the course of at least a year, this poor fellow, desperate to drive traffic to his React Native library, has taken the time to spam 10, 20, 30 issues, ostensibly promoting a solution to their woes, where really he's just trying to put forward his own solution:

https://github.com/alinz/react-native-share-extension/issues/206#issuecomment-636508733
https://github.com/alinz/react-native-share-extension/issues/205#issuecomment-636508771
https://github.com/alinz/react-native-share-extension/issues/204#issuecomment-636508797
https://github.com/alinz/react-native-share-extension/issues/203#issuecomment-636508834
https://github.com/alinz/react-native-share-extension/issues/202#issuecomment-636508860 to name but a few.

Pet peeves

Things on a list that annoy me: hypocrisy, deceitfulness, and bare-faced and brazen manipulation -- especially in a time of fake news. I don't have time, (and others shouldn't waste their time) on the lazy and feckless.

So, I decided to take this guy to task by opening an issue on his lib's Github repo:

I wasn't going to sit by and allow this guy to mislead and misrepresent. It's just not how things should be done.

The Audacity!

So, after some two weeks have passed, this guy hasn't responded to my issue, until today (2020-08-05) with what can only be described as pure chutzpah! Not only does he close the issue, he:

deletes the content so no one can see it
(and because the issue is mentioned on the source repo) he changes the title so it looks like I've thanked him for it!

I guess I should give him credit for his willingness to commit to the charade, but damn!

Conclusion: Dont' be a dick

The point I'm trying to make here is that this is so weird. It's great that you want to create something open source and give it away for the world to enjoy -- this is a selfless act that is repeated every day and has given us some of history's greatest software (Linux anyone?).

But to seemingly be doing this to further you own interests, or to gain exposure, or for some perceived gains in professional status, and to self promote in such an opaque and clandestine way, spamming someone else's repo to take users, it's not really the sign of a professional who you'd want to work with. It makes me, and should make you, very wary about using their library.

You can see the offending package at https://github.com/ajith-ab/react-native-receive-sharing-intent/issues/27