Tag: standards

PHP: Countries and currencies

Many software projects deal with the lists of countries and currencies.  Some of the most common tasks include country an currency dropdowns, country flags next to the IP, or pre-filling country codes in phone numbers.

All of that information is of course standardized and you often just need a library or two to provide and use it.  And there are many of those.  We’ve been mainly using these two:

Today, however, I came across a better option – antonioribeiro/countries, which is a collection of country and currency information for Laravel PHP framework.  Laravel is not required though.  This library provides way more information and in a much more flexible way.  It includes:

  • 266 countries (with more codes, common names, official names, and more)
  • 256 currencies
  • 1,570 flags
  • 248 geometry maps
  • 248 topology maps
  • 4,526 states
  • 7,376 cities
  • and a lot more!

Crell/ApiProblem – a simple implementation of the api-problem specification

I’ve been working with REST/RESTful APIs for a while now.  They are usually a lot better than the SOAP or XML-RPC stuff we had before.  But they are also not perfect.  Error handling and reporting is a common area between many implementations that needs more attention and consistency.  Turns out, there is, I’ve just somehow never heard of it – RFC7807 defines “Problem Details for HTTP APIs”.

I’ll need to look more into this and see if and how it is better than a variety of things I’m using now.  Gladly, there is even a PHP library to help with that – Crell/ApiProblem:

This library provides a simple and straightforward implementation of the IETF Problem Details for HTTP APIs, RFC 7807.

RFC 7807 is a simple specification for formatting error responses from RESTful APIs on the web. This library provides a simple and convenient way to interact with that specification. It supports generating and parsing RFC 7807 messages, in both JSON and XML variants.

HTTP/3 via QUIC

As we are still trying to get the grip with HTTP/2, the world is moving on.  Here’s the blog post with some initial details on HTTP/3 and QUIC.  Turns out, we moving away from TCP to UDP with encryption.

Here are more details from the CloudFlare blog post.

Let the fear, uncertainty, and doubt begin!

Documenting lists with Swagger

Swagger is a great tool for documenting APIs.  Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation.

We use Swagger a lot at work.  We’ve even pushed the bar slightly, but automatically generating the API documentation on the fly, to match the rest of our Qobrix functionality.  Whenever you change the database schema or the configuration of the fields, the changes are also reflected immediately in the API documentation.  And it works great!

One of the things that we haven’t done though until very recently is the documentation of the list fields.  Swagger provides the enum to document the values that can go into the field, but it’s not very helpful, when the values are not obvious.  Country codes and currency symbols work well, as they are common knowledge.  But if you have something custom, there needs to be a set of labels associated with the set of values.

The other day we decided that something is better than nothing, and added the documentation of the values as part of the field description (the property is described on the same page as enum above).  Here’s the Pull Request with the tiniest of changes.  And here’s how it looks in Swagger:

I admit, it’s not the prettiest of things, but at least the hints for the developers are there.  Also, since the list of labels uses a specific format, it’s quite easy to parse it out of the Swagger JSON automatically and reuse in third-party applications and services (like a website, connected to the system via the API).

While browsing around, I’ve also noticed that Swagger is growing and expanding. There is a new version of the specification – version 3.0, which has also been re-branded as OpenAPI Specification (see OpenAPI Initiative).  Here’s a great blog post that describes the differences between this and the previous versions, and here’s the migration guide for those who need it.

If you are working with PHP, zircote/swagger-php is the way to go.  It already even support the version 3.0.  If you are using the CakePHP framework, alt3/cakephp-swagger is the plugin for you (version 3.0 is not yet supported, but I’m sure it’ll get there soon).