Skip to main content

API Guidelines

APIs within WeatherStack should always attempt to return a value, and give the user the most information possbible about an error. For example, if the request is malformed, tell the user what part of the request is malformed, rather than just returning 400.

The API route can begin with /api/, but if possible just /.

Versioning​

If this is a significant API that could have breaking changes if altered (If it impacts a lot of other services) it must have a versioning system, so that legacy routes can still be accessed by difficult to change services.

For example:

  • /v1/health/liveliness - Check version 1 liveliness
  • /v2/health/liveliness - Check version 2 liveliness

Methods​

Methods must be used for their correct purposes.

MethodPurpose
GETRetrieving data
POSTCreating new data/resources
PUT/PATCHUpdating existing data/resources
DELETERemoving existing data/resources

HTTP codes​

HTTP return codes must also be used for their correct purposes.

Required API routes​

Any API must have the following API routes.

Information API route​

Depending on the API, the root / should be used to easily identify what API it is. If the root is being used for something else, it can be /info/.

This must return the following data:

  • Version information (Current version code)
  • API name
  • Repository URL
  • A cool little message (Can be anything, even randomly selected)

Health API routes​

There are 2 API routes that are required for health checking, and some other service-specific API routes.

Liveliness​

This is a very quick API route that simply returns a small message (can be anything) saying that it's alive. This API route should be /health/liveliness/.

For example:

{
    "success": true,
    "code": 200,
    
    "message": "Number 5 is alive!"
}

Information​

This is an informative API route, as it should return information such as uptime, and other service-specific values, and of course, a small message (can be anything). THis API route should be /health/info/.

For example:

{
    "success": true,
    "code": 200,

    "message": "Dude, you can't run from the future!",

    "stats": {
        "uptime": 3538688.83811651,
        "uptime_human": "1 months 10 days 12 hours 24 minutes 32 seconds 838 milliseconds"
    }
}