restapinaming-conventionsrestful-architecture

Best name for an API endpoint that checks if a username is valid or not

I'm going to design a RESTful API which checks if there's anything wrong (e.g. duplicate, invalid characters, or names listed in the blacklist ... ) with the username provided by the caller.

The API should return the check result (valid or invalid) to the caller so that the caller knows if he can use this username or not.

How can I name the API endpoint?

I originally thought that GET /checkUserName/{username} or GET /isUserNameValid/{username} are good names for my API. But I'm not sure if they are really good. And I don't know how to convenience others to accept the names I came up with.

GET is the http method. username is a parameter provided by the caller.

I've read the following two articles:

10 best practices for better restful api

RESTful API Designing guidelines — The best practices

But it seems like that the name of my API cannot fit into all the guidelines described in the above articles.

One of the guidelines says

Use nouns but no verbs

By following this guideline, GET /checkUserName/{username} is not appropriate. Because it contains the verb check.

GET /isUserNameValid/{username} is not appropriate, either. Because is is a verb.

So what's the best name for the API if I have to follow the guidelines of RESTful design?

I couldn't think of an appropriate name that contains no verb.

Solution

  • It sounds like you're trying to build an RPC API but want to call it REST. :)

    A little background information on the differences.

    Normally I'd try to suggest refactoring, as validation in general is best handled on the server-side, with JSON Schema being defined and shared with the frontend so that they can also use a JSON Schema validator locally and match the validation.

    The "duplicate" criteria is the one thing that JSON Schema could not validate against, and I'm sure the use-case is one of those username boxes that gives instant feedback on how good the username is before submitting the actual form.

    So a few approaches.

    1.) Microservice

    Buzzword yes, but often when it comes time for a tiny little endpoint that needs to do one specific thing, especially if that thing is a bit RPC and the rest of the API is a REST API, I use a single little service.

    Often APIs for the sake of RAD are written in PHP or Ruby and have some giant framework, but for some little system that needs to work quick often I've used something smaller like Go.

    You could of course use the same language and the usual Sinatra vs Rails difference comes into play. This could just be a single RPC

    2.) REST Crowbar

    So to make it be RESTful, you just want to create a new resource type, which would need to be something like:

    POST /username-checks

{ "username": "foo" }

    I don't much like this, but it could be due to there being a substantially better design that we've not even considered yet.

    3.) Big Brother

    As soon as the registration form has something like an email entered, save everything that has been filled out in the form so far.

    This could be a POST /users with the populated fields and default to having a status of "potential", or it could be some other POST /user-potential resource. That's up to you, but the idea of posting very little, very early has two benefits.

    1. You can do abandoned cart style reminders to people to "finish their account", which is becoming increasingly common in the e-commerce world
    2. Once you have created this resource, you have a UUID which you can PATCH against.

    Trying to PATCH with an invalid username would give you validation errors.

    PATCH /users/<uuid>

{ username: "admin" }

    For your errors, consider using RFC 7807: API Problems, it's fantastic.

    I'm not trying to set up a false trichotomy here, there's probably a few other approaches but I'd really consider 1 or 3, with 2 being a maybe I threw in for the sake of giving a complete answer.