MinApiLib.HashedIds
11.0.0
dotnet add package MinApiLib.HashedIds --version 11.0.0
NuGet\Install-Package MinApiLib.HashedIds -Version 11.0.0
<PackageReference Include="MinApiLib.HashedIds" Version="11.0.0" />
<PackageVersion Include="MinApiLib.HashedIds" Version="11.0.0" />
<PackageReference Include="MinApiLib.HashedIds" />
paket add MinApiLib.HashedIds --version 11.0.0
#r "nuget: MinApiLib.HashedIds, 11.0.0"
#:package MinApiLib.HashedIds@11.0.0
#addin nuget:?package=MinApiLib.HashedIds&version=11.0.0
#tool nuget:?package=MinApiLib.HashedIds&version=11.0.0
MinApiLib.HashedIds
Expose integer ids as short hashes in routes and JSON, using the Hashids library.
Installation
dotnet add package MinApiLib.HashedIds
Usage
Configure the hasher when the application starts:
global using MinApiLib.HashedIds;
// ...
builder.Services.AddHashedIds(op =>
{
op.Passphrase = builder.Configuration["HashedIds:Passphrase"];
op.MinHashLength = 8; // optional
});
AddHashedIds throws if the passphrase is null, and using a HashedId before calling it throws an InvalidOperationException. Keep the passphrase and the minimum length stable: changing them changes public ids, and breaks the ones clients have stored.
Use HashedId in requests and responses. It converts implicitly from and to int:
public record struct Request([FromRoute] HashedId Id);
public record struct Response(HashedId Id, string Name);
public record GetThing() : GetHandler<Request>("/things/{id}")
{
protected override IResult Handle(Request request)
{
int id = request.Id;
return Results.Ok(new Response(id, "John Doe"));
}
}
$ curl "http://localhost:5000/things/Wd"
{"id":"Wd","name":"John Doe"}
For long keys, use HashedLongId, which works the same way.
Invalid values
An invalid value in a route, a query string or a JSON body gets a 400 before the handler runs. In the Development environment, ASP.NET Core shows this 400 with its exception page.
A missing JSON property isn't an invalid value: it gets the default, 0. To reject it, mark the property required:
public class RequestBody
{
public required HashedId OwnerId { get; set; }
}
[Required] has no effect, because HashedId is a non-nullable value type. A valid hash can still point to an entity that doesn't exist, so look it up in the handler.
With Entity Framework
Cast to int in queries and key lookups:
var thing = await db.Things.FirstOrDefaultAsync(t => t.Id == (int)request.Id, cancellationToken);
var other = await db.Things.FindAsync(new object[] { (int)request.Id }, cancellationToken);
Assigning an int to a HashedId property works inside a Select projection. Filter and sort before it, on the entity's columns:
db.Things.OrderBy(t => t.Name).Select(t => new ResponseItem { Id = t.Id, Name = t.Name });
With Swagger
Map the type so it's documented as a string. With Swashbuckle 10:
builder.Services.AddSwaggerGen(c => c.MapType<HashedId>(() => new OpenApiSchema { Type = JsonSchemaType.String }));
On Swashbuckle 6, use new OpenApiSchema { Type = "string" }.
Limitations
- It isn't a security mechanism. Hashids obfuscates ids, without encrypting them. Keep checking access to each resource.
- Negative values have no hash.
- The hasher is static and shared by the whole process, because model binding and JSON conversion use it without access to dependency injection. One process can only use one configuration, and the last call to
AddHashedIdswins.
Upgrading
An invalid hashed id in a JSON body used to reach the handler as -1. Now the request is rejected with a 400.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Hashids.net (>= 1.7.0)
-
net11.0
- Hashids.net (>= 1.7.0)
-
net8.0
- Hashids.net (>= 1.7.0)
-
net9.0
- Hashids.net (>= 1.7.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.