Instead, you need to create an "OpenID Connect" provider. Here's how.

OpenSteetMap

As per the OAuth documentation you will need to:

• Register a new app at https://www.openstreetmap.org/oauth2/applications/
• Give it a name that users will recognise
• Give it a redirect of https://Your Auth0 Tenant.eu.auth0.com/login/callback
• Tick the box for "Sign in using OpenStreetMap"

Once created, you will need to securely save your Client ID and Client Secret.

Auth0

These options change frequently, so use this guide with care.

• Once you have logged in to your Auth0 Tennant, go to Authentication → Enterprise → OpenID Connect → Create Connection
• Provide the new connection with the Client ID and Client Secret
• Set the "scope" to be openid
• Set the OpenID Connect Discovery URL to be https://www.openstreetmap.org/.well-known/openid-configuration
• In the "Login Experience" tick the box for "Display connection as a button"
• Set the favicon to be https://blog.openstreetmap.org/wp-content/uploads/2022/07/osm-favicon.png or other suitable graphic

Next Steps

We're not quite done, sadly.

The details which OSM sends back to Auth0 are limited, so Auth0 is missing a few bits:

{
    "created_at": "2026-02-29T12:34:56.772Z",
    "identities": [
        {
            "user_id": "openstreetmap-openid|123456",
            "provider": "oidc",
            "connection": "openstreetmap-openid",
            "isSocial": false
        }
    ],
    "name": "",
    "nickname": "",
    "picture": "https://cdn.auth0.com/avatars/default.png",
    "preferred_username": "Terence Eden",
    "updated_at": "2026-02-04T12:01:33.772Z",
    "user_id": "oidc|openstreetmap-openid|123456",
    "last_ip": "12.34.56.78",
    "last_login": "2026-02-29T12:34:56.772Z",
    "logins_count": 1,
    "blocked_for": [],
    "guardian_authenticators": [],
    "passkeys": []
}

Annoyingly, Auth0 doesn't set a name or nickname - so you'll need to manually get the preferred_username, or create a "User Map":

{
  "mapping_mode": "use_map",
  "attributes": {
    "nickname": "${context.tokenset.preferred_username}",
    "name":     "${context.tokenset.preferred_username}"
  }
}

There's also no avatar image - only the default one.

Getting the Avatar Image

The OSM API has a method for getting user data.

For example, here's all my public data: https://api.openstreetmap.org/api/0.6/user/98672.json - thankfully no authorisation required!

{
  "user": {
    "id": 98672,
    "display_name": "Terence Eden",
    "img": {
      "href": "https://www.gravatar.com/avatar/52cb49a66755f31abf4df9a6549f0f9c.jpg?s=100&d=https%3A%2F%2Fapi.openstreetmap.org%2Fassets%2Favatar_large-54d681ddaf47c4181b05dbfae378dc0201b393bbad3ff0e68143c3d5f3880ace.png"
    }
  }
}

Alternatively, you can use the Unavatar service to get the image indirectly.

I hope that's helpful to someone!

The README says to download from this link. Huh, I'm not sure how to unarchive .tar.xz files - guess I'll search for that. Right, it says run setup.sh hmm, that doesn't work. Oh, I need to set the permissions. What was the chmod command again? OK, that's working. Wait, it needs sudo. Let me run that again. Hang on, am I in the right directory? Here it goes. What, it crapped out. I don't have some random library - how the hell am I meant to install that? My distro has v21 but this requires <=19. Ah, I also need to upgrade something which isn't supplied by repo. Nearly there, just need to compile this obscure project from SourceForge which was inexplicably installed on the original dev's machine and then I'll be good to go. Nope. Better raise an issue on GitHub. Oh, look, it is tomorrow.

As a developer, you probably don't want to answer dozens of tickets complaining that users are frustrated with your work. You thought you made the README really clear and - hey! - it works on your machine.

There are various solutions to this problem - developers can release AppImages, or Snaps, or FlatPaks, or Docker or whatever. But that's a bit of stretch for a solo dev who is slinging out a little tool that they coded in their spare time. And, even those don't always work as seamlessly as you'd hope.

There's an easier solution:

1. Follow the steps in your README
2. See if they work.
3. …
4. That's it.

OK, that's a bit reductive! There are a million variables which go into a test - so I'm going to introduce you to a secret zeroth step.

0. Spin up a fresh Virtual Machine with a recent-ish distro.

If you are a developer, your machine probably has a billion weird configurations and obscure libraries installed on it - things which definitely aren't on your users' machines. Having a box-fresh VM means than you are starting with a blank-slate. If, when following your README, you discover that the app doesn't install because of a missing dependency, you can adjust your README to include apt install whatever.

OK, but how?

Personally, I like Boxes as it gives you a simple choice of VMs - but there are plenty of other Virtual Machine managers out there.

Pick a standard OS that you like. I think the latest Ubuntu Server is pretty lightweight and is a good baseline for what people are likely to have. But feel free to pick something with a GUI or whatever suits your audience.

Once your VM is installed and set up for basic use, take a snapshot.

Every time you want to test or re-test a README, revert back to the original state of your box. That way you won't have odd half-installed packages laying about.

Your next step is to think about how much hand-holding do you want to do?

For example, the default Debian doesn't ship with git. Does your README need to tell people to sudo apt install git and then walk them through configuring it so that they can git clone your repo?

Possibly! Who is your audience? If you've created a tool which is likely to be used by newbies who are just getting started with their first Raspberry Pi then, yeah, you probably will need to include that. Why? Because it will save you from receiving a lot of repeated questions and frustrated emails.

OK, but most developers will have gcc installed, right? Maybe! But it doesn't do any harm to include it in a long list of apt get … anyway, does it? Similarly, does everyone know how to upgrade to the very latest npm?

If your software is designed for people who are experienced computer touchers, don't fall into the trap of thinking that they know everything you do. I find it best to assume people are intelligent but not experienced; it doesn't hurt to give slightly too much detail.

The best way to do this is to record everything you do after logging into the blank VM.

0. Restore the snapshot.
1. Log in.
2. Run all the commands you need to get your software working.
3. Once done, run history -w history.txt
   • That will print out every command you ran.
4. Copy that text into your README.

Hey presto! You now have README instructions which have been tested to work. Even on the most bare-bones machine, you can say that your README will allow the user to get started with your software with the minimum amount of head-scratching.

Now, this isn't foolproof. Maybe the user has an ancient operating system running on obsolete hardware which is constantly bombarded by cosmic rays. But at least this way your issues won't be clogged up by people saying their install failed because lib-foobar wasn't available or that ./configure had fatal errors.

A great example is the Opus Codec README. I went into a fresh Ubuntu machine, followed the readme, ran the above history command, and got this:

sudo apt-get install git autoconf automake libtool gcc make
git clone https://gitlab.xiph.org/xiph/opus.git
cd opus
./autogen.sh
./configure
make
sudo make install

Everything worked! There was no missing step or having to dive into another README to figure out how to bind flarg 6.9 with schnorp-unstable.

So that's my plea to you, dear developer friend. Make sure your README contains both the necessary and sufficient information required to install your software. For your sake, as much as mine!

Wait! You didn't follow your own advice!

You're quite right. Feel free to send a pull request to correct this post - as I shall be doing with any unhelpful READMEs I find along the way.

So I want to host my own Git instance for my personal projects. I'm experimenting with https://git.edent.tel/

It isn't quite self-hosted; I'm paying PikaPod €2/month to deal with the hassle of hosting and updating the software. I get to point my domain name at it which means I can always change the underlying service if I want. For example, it uses Gitea and I might want to switch to Forgejo later.

So far, it works. But there are a few significant drawbacks.

Network Effects

A large service like GitHub has network effects which are incredible. It feels like 90%+ of all developers have an account there. That means if someone wants to leave a comment or send a PR there is no barrier to entry. That's huge! There are a bunch of popular FOSS projects which make me sign up for yet another service when all I want to do is send a simple bug report which I find deeply annoying.

Luckily, Gitea has built in support for various OAuth providers. So I've set up single-sign-on with Gits Hub and Lab.

I asked people how easy it was to use - most people were able to use it, although a few people wanted a local-only account.

But is is still a bit of a faff. Even a little bit of hassle turns people away.

Forking isn't Federated

Suppose you want to make a Pull Request or just take a copy of the code. At the moment, you have to create a fork on my server. There's no way to easily fork something to your GitHub or personal server.

You can git clone the repo to your local machine, and you can manually move it elsewhere, but there's no way to send a PR from your repo to mine.

There's also no way for users to find other forks. Perhaps the upcoming ForgeFed proposals will fix things - but it doesn't exist yet.

As pointed out in "Let's Make Sure Github Doesn't Become the only Option" - most of the tooling of git hosting platforms isn't adequate for modern needs.

Discoverability

The easiest way to find code at the moment is to search GitHub. Moving my stuff to a different site means it will only be discovered by a general search engine.

I want people to find and use my code. If that's hard, they won't. I can point existing users to the repo - but it still cuts down on discovery.

Admin Hassles

Although PikaPods takes care of all the hosting administration, there's still the faff of setting up all of Gitea's options.

If I get hit by an automated spam attack, it'll be up to me to clean it up.

I'm not sure if I have the time, patience, or expertise to correctly and safely configure everything. Time spent administrating is time not spent coding.

Sponsorship

I get a little bit of money when people sponsor me on GitHub. There's no "sponsor" option on Gitea and, even if there was, the network effects of GitHub are substantial. Getting people to enter their credit card info into a random site isn't as convenient as clicking a button in GitHub.

Now What?

My most popular Github repo has around 140 contributors. I genuinely don't think I could attract that many people to OAuth onto my personal git hosting service.

Gitea seems to have a mixed reputation. But it's the only one offered by PikaPods.

There are interesting discussions about how to replace GitHub but they're only in the early stages.

Although €2/mo isn't a huge amount, I've gotten used to having free services on GitHub / GitLab / CodeBerg.

So this, I think, is my plan:

1. Leave my popular / sponsored repos on GitHub
2. Move my smaller repos to https://git.edent.tel/
3. Create new repos in there as well

I'm also going to look for a hosted Forgejo instance which lets me use my own subdomain - hopefully at a cheaper or comparable price. If you have any recommendations - please let me know!

Think about the last time you started using a new API...

• Fill in a tediously long registration form
• Set up billing in case you go over the free trial limits
• Wait for a confirmation email
• Unsubscribe from all the marketing emails
• Find the quickstart documentation
• Realise it is outdated and consider raising an issue on the GitHub issues graveyard
• Generate an API key and configure all its scopes
• Install a 3rd party NPM library and a gigabyte of required packages
• Work out how to authenticate the request - hard given the tutorial uses V1.3.4 and you're on V1.3.4.0.1b
• Send the first request, and realise that you had to manually add your IP address to the allow-list
• Try again, but realise you need to sign the request with a unique timestamp
• Receive an HTTP 429 error for sending too many requests
• Have a pint
• Try again, get an HTTP 200! Success! You're a real developer now!

The above is only a minor exaggeration. Every time I sign up to play with a new API, I'm grimly aware of my own mortality. Every minute I waste doing battle with your incomplete documentation and dreadful attitude to new users, is a minute I could spend doing something more fun instead.

Please, I beg of you, optimise your Time To 200!

In an uncharacteristic display of openness, Twitter's API allows developers to get direct access to video.

This is a quick blog post to explain how you get access, and what you can do with the information.

I presuppose that you're already familiar with the Twitter API and know how to make basic calls.

Entities

Upon requesting a status (either individually or as part of a timeline) your program will receive metadata about the post, stored in the entities node of the JSON.

One of these entities will be the imaginatively named "extended_entities".

If we request this specific Tweet:

katie

@katiemoffat

A dull video of my cat to test twitter videos pic.x.com/cGazAn7H3E

---

The "extended_entities" looks like this :

"extended_entities": {
    "media": [
      {
        "id": 567972074346807300,
        "id_str": "567972074346807296",
        "indices": [
          46,
          68
        ],
        "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/567972074346807296/pu/img/uz53Ap4wEah7cV50.jpg",
        "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/567972074346807296/pu/img/uz53Ap4wEah7cV50.jpg",
        "url": "http://t.co/cGazAn7H3E",
        "display_url": "pic.twitter.com/cGazAn7H3E",
        "expanded_url": "http://twitter.com/katiemoffat/status/567972190639022080/video/1",
        "type": "video",
        "sizes": {
          "small": {
            "w": 340,
            "h": 340,
            "resize": "fit"
          },
          "thumb": {
            "w": 150,
            "h": 150,
            "resize": "crop"
          },
          "medium": {
            "w": 600,
            "h": 600,
            "resize": "fit"
          },
          "large": {
            "w": 720,
            "h": 720,
            "resize": "fit"
          }
        },
        "video_info": {
          "aspect_ratio": [
            1,
            1
          ],
          "duration_millis": 6605,
          "variants": [
            {
              "bitrate": 832000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/480x480/eU1s1ig_skHgeRjB.mp4"
            },
            {
              "content_type": "application/x-mpegURL",
              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/pl/tr7sF7aHBPOCuL8H.m3u8"
            },
            {
              "bitrate": 832000,
              "content_type": "video/webm",
              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/480x480/eU1s1ig_skHgeRjB.webm"
            },
            {
              "bitrate": 1280000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/720x720/njkDGgpJBpsTjQD3.mp4"
            },
            {
              "bitrate": 320000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/240x240/Gye4gcWtlJq8zXhF.mp4"
            }
          ]
        }
      }
    ]
  },

As well as a static thumbnail, we are also given a list of direct links to the video files. extended_entities->media->video_info->variants

Here's where things get a little confusing...

• Three of the videos are MP4 files - each with a different bitrate.
• There is one WEBM video.
• Finally, there's an HTTP Live Streaming link suitable for iOS.

The videos are in an unordered list, so you'll need to parse each one carefully to pick the right format.

One Video To Rule Them All

It's tricky to know which file to display to a user. The lowest bitrate MP4 will probably play on most devices. The WEBM is good for modern browsers apart from IE. The streaming link is unlikely to work with desktop machines and older phones.

There's no filesize information, so you can't present that to a user and allow them to make a choice.

There's no direct access to the resolution of the video. If you look at the URL : https://video.twimg.com/ext_tw_video/567972074346807296/pu/vid/240x240/Gye4gcWtlJq8zXhF.mp4 You should be able to extract the resolution from the string. In the above case, it's 240*240.

Unless you are absolutely sure of your user's device capabilities, stick to the MP4 version. Hopefully the lowest resolution will always be the last element of the array.

Ideally, I would have liked to have seen Twitter provide a canonical URL - point the user at that and let Twitter decide on the best format and directly serve it. At the very least, it would be helpful to provide filesize and resolution in the metadata.

In HTML5, it's easy to add multiple sources to allow the browser to determine which one to play :

<video controls>
  <source src="foo.m3u8" type="application/x-mpegURL">
  <source src="foo.webm" type="video/webm">
  <source src="foo.mp4"  type="video/mp4">
  Your browser does not support the <code>video</code> element.
</video>

That should display like this :

I'm not aware of a (simple) way to advertise differing bitrates and resolutions. You can use hacks like media queries to determine screensize, or try using a video playback solution like Video.js;

If you want a fuller explanation, I advise reading Dive Into HTML5's Video section.

Searching For Videos

There's nothing in the search API which allows you to specify that you only want results with videos. A hacky way to get them is to search for the string "/video/1". You might get a few false positives, but it's all that's available for now.

Where Next?

Hopefully we'll see more 3rd party apps supporting the display of video - I'll be updating Dabr shortly.

At the moment, the Twitter API only allows Animated GIFs to be uploaded by third party clients - video is restricted to official apps. I hope that will change in the near future.

I can't wait to see what interesting art and data comes from this.

OMG! Some star LOVES Samsung.

Back when Twitter started, they used to advertise which Twitter clients people used. You could see that Stephen Fry preferred Feathers, and that I used Dabr. All was well. Then, of course, Twitter went to war with its third party developers. They cut their API limits, reduced their functionality, and obliterated all mention of third party clients.

Which means that you can't see that certain "celebs" are hypocrites.

Looking at the underlying data of the above tweet shows that it was sent from "Twitter for iPhone".

Look, I don't really care that people lie on Twitter. I care that Twitter facilitates their lies.

I stumbled on this fantastic quote from Greg Parker:

Greg Parker

@gparker

A programming language is a user interface for developers. Language authors should learn from HCI principles.

---

When I first started learning C++ (back in the bad old days) I was convinced that any 1st year student could design a better programming language. One which behaved in a sane fashion without a lot of legacy cruft. In many ways, PHP is that programming language. It's simple, logical, and works without having to know lots of esoteric computer science.

I see API design in the same way. Most of the APIs I come in contact with were obviously designed by the original developer for the original developer - with no thought of those who would come after her. Often, they're designed for one specific internal usage, reluctantly opened to the public, and never updated to account for how people actually use them. Oh, and you can forget about decent documentation!

One hackathon I went to a few weeks ago had a Developer Relations employee stand up and say:

Who wants to use our API? It uses SOAP - sorry. If you want documentation - come see me because it's not on the website. Oh, and it's read only. Let me know as soon as possible because it takes 6 hours to approve your API key.

This is madness. Developers are human too! They need some HCI love between them and their APIs.

So, here are my hastily scribbled thoughts on what an API needs at a minimum to entice the busy developer.

I don't think any of these are Earth-shattering, but it's amazing how many APIs fail to meet even these basic requirements.

Easy Access

• Don't make me register, set up an account, or fill in a load of forms - I just want to see what I can do with you before I make a commitment.
• Do give me an Apigee console - or similar - so I can see for myself what's happening.
• Don't give me absurd key signing requirement - I should be able to call the API from a web browser just by typing stuff in.
• Do make it as easy as possible for me to get started - get your CEO (or similar) and see how long it takes her to set up an account & launch her first call. If it's more than 5 minute, go back to the drawing board.

Example Code

• Don't tell me what your API can do - show me a few cool calls to start me off.
• Just because you love Ruby, doesn't mean everyone does. Show examples in a variety of languages.
• Provide examples of code which won't work and explain why.
• Comment your code. It may be obvious to you what "choes=17|L" means, but it may not be to me.

Documentation

• This is possibly the most important area.
• I need to know what I can do, how I can do it, why I should do it a certain way, and what response to expect.
• For. Every. Single. Function.
• If you can't document your API, people can't use it.

Full Enumeration of Responses

• Tell me the full range of response I can expect.
• A good example is Twitter's "retweet_count", the documentation used to imply that the response would always be an integer. However, it would occasionally respond with a string of "100+". Naturally, this meant developers would write code expecting ints which would fail whenever a string was encountered. If you can't tell me what responses to expect - how can I code something which handles those responses correctly?
• What error codes are you likely to throw?

Variety of Response Language

• Yes, you love XML. Guess what? I don't!
• The customer is always right. If the customer (developer) wants JSON, XML, PHPobject, or just plain text - you should give it to them.
• It's the API designer's job to make life easy for developers - so reply in whatever formats the developer wants.

Human Readable Response

• Developers are humans! Yes! It's true! And they can't all pretty-print JSON in their heads. Give them something they can read without resorting to external tools.
• The Wikipedia API is a brilliant example of this. They have a human readable response for their API calls.
• Unless you have a very good reason not to - all your responses should be pretty-printed. It helps with debugging and makes life just that little bit easier for a struggling developer.

Human Readable Requests

• Developers are humans! Yes! It's true! And they can't all remember every little acronym in their heads. Give them something they can read without resorting to documentation.
• What's easier to remember "gnxID" or "getNextId"?
• Keep your parameters consistent.

Unchanging

• Consistency is a virtue. If you have two similar APIs (say, search & read) they should take the same parameters and produce identically formatted responses.
• If you have to change the way your API responds, or the way it accepts request, that's fine - but use versioning so that developers don't have to update their code if they don't want to.
• Never deprecate anything! Once an embedded device has had its firmware burned, it's unlikely to ever be updated. If people or services rely on you, it's simply unacceptable to kill something off. Remember, not every developer or end user can update their software.

Simplicity

• Perhaps the most important of all HCI commandments - Keep It Simple.
• Don't engage in a needless dance where developers have to take several steps to do a single action.
• Try to explain what you're doing in a single sentence. If you can't - it's probably too complicated.

Libraries

• I'm sure you're very proud that your community has created some libraries - but they're not good enough.
• Want people to use your API? Provide libraries in a wide variety of languages.
• Update and support those libraries.

Detailed Errors

• It's not enough to say an error has occurred. Say why it has occurred.
• Error codes must always be accompanied by human readable error messages.
• Do you really need to throw an error? Can your API take a "best" guess at what the user was trying to do? Be generous in what you accept.

Feedback

• Your API sucks. Accept that.
• Provide a mechanism where people can feed back what they think is broken, poorly implemented, missing, or just plain confusing.
• Discuss the feedback openly. See what the rest of your community thinks.
• Act on feedback. If a feature request hasn't been acted on after 6 months, you've probably failed.

So What?

There is nothing new in this post to the seasoned developer. But as Matt Gemmell reminded me recently - some people just don't know the basics.

If you're interested in making your API useful for developers, you have to treat it like any other product. You have to consider HCI factors, you have to do product testing, design, and planning.

Your API is a product. Treat your developers as you would your most profitable users.

Further Reading

There are many books on this subject - the two I recommend are: Basics of the Unix Philosophy (free). The Design of Everyday Things (paper or ebook).