Passing DateTimeOffset as WebAPI query string

Question

I\'ve got a WebAPI action that looks like so:

[Route(\"api/values/{id}\")]
public async Task Delete(string id, DateTimeOffset date         


        

Answer 1

Answer

To send a DateTimeOffset to your API, format it like this after converting it to UTC:

2017-04-17T05:04:18.070Z

The complete API URL will look like this:

http://localhost:1234/api/values/1?date=2017-04-17T05:45:18.070Z

It’s important to first convert the DateTimeOffset to UTC, because, as @OffHeGoes points out in the comments, the Z at the end of the string indicates Zulu Time (more commonly known as UTC).

Code

You can use .ToUniversalTime().ToString(yyyy-MM-ddTHH:mm:ss.fffZ) to parse the DateTimeOffset.

To ensure your DateTimeOffset is formatted using the correct timezone always use .ToUniversalTime() to first convert the DateTimeOffset value to UTC, because the Z at the end of the string indicates UTC, aka "Zulu Time".

DateTimeOffset currentTime = DateTimeOffset.UtcNow;
string dateTimeOffsetAsAPIParameter = currentDateTimeOffset.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
string apiUrl = string.Format("http://localhost:1234/api/values/1?date={0}", dateTimeOffsetAsAPIParameter);

Answer 2

Use the ISO 8601 datetime format specifier:

$"http://localhost:1234/api/values/1?date={DateTime.UtcNow.ToString("o")}"

or

$"http://localhost:1234/api/values/1?date={DateTime.UtcNow:o}"

Answer 3

To achieve this, I'm using

internal static class DateTimeOffsetExtensions
{
    private const string Iso8601UtcDateTimeFormat = "yyyy-MM-ddTHH:mm:ssZ";

    public static string ToIso8601DateTimeOffset(this DateTimeOffset dateTimeOffset)
    {
        return dateTimeOffset.ToUniversalTime().ToString(Iso8601UtcDateTimeFormat);
    }
}

Answer 4

The problem is being described exactly by the 400 response message, although it could have been more clear. The route, as defined by the attribute, only expects a parameter id, but the Delete method expects another parameter called date.

If you want to provide this value using the query string, you'll need to make that parameter nullable, by using "DateTimeOffset?", which would also transform it into an optional parameter. If the date is a required field, consider adding it to the route, like:

[Route("api/values/{id}/{date}")]

OK, ignore what I typed above, it's just a formatting problem. Web API has trouble figuring out the culture needed to parse the given value, but if you try to pass on DateTimeOffset using a JSON format in the query string, like 2014-05-06T22:24:55Z, that should work.

Answer 5

Create a custom type converter as follows:

public class DateTimeOffsetConverter : TypeConverter
{
    public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
    {
        if (sourceType == typeof(string))
            return true;

        return base.CanConvertFrom(context, sourceType);
    }

    public override bool CanConvertTo(ITypeDescriptorContext context, Type destinationType)
    {
        if (destinationType == typeof(DateTimeOffset))
            return true;

        return base.CanConvertTo(context, destinationType);
    }

    public override object ConvertFrom(ITypeDescriptorContext context, CultureInfo culture, object value)
    {
        var s = value as string;

        if (s != null)
        {
            if (s.EndsWith("Z", StringComparison.OrdinalIgnoreCase))
            {
                s = s.Substring(0, s.Length - 1) + "+0000";
            }

            DateTimeOffset result;
            if (DateTimeOffset.TryParseExact(s, "yyyyMMdd'T'HHmmss.FFFFFFFzzz", CultureInfo.InvariantCulture, DateTimeStyles.None, out result))
            {
                return result;
            }
        }

        return base.ConvertFrom(context, culture, value);
    }

In your startup sequence, such as WebApiConfig.Register, add this type converter dynamically to the DateTimeOffset struct:

TypeDescriptor.AddAttributes(typeof(DateTimeOffset),
                             new TypeConverterAttribute(typeof(DateTimeOffsetConverter)));

You can now just pass DateTimeOffset values in the compact form of ISO8601, which omits hyphens and colons that interfere with the URL:

api/values/20171231T012345-0530
api/values/20171231T012345+0000
api/values/20171231T012345Z

Note that if you have fractional seconds, you may need to include a trailing slash in the url.

api/values/20171231T012345.1234567-0530/

You could also put it in the querystring if you like:

api/values?foo=20171231T012345-0530

Answer 6

The current accepted answer throws away the time zone information, which in some cases is important. The following maintains the time zone and doesn't lose any precision. It also keeps your code succinct when building a query string.

public static string UrlEncode(this DateTimeOffset dateTimeOffset)
{
     return HttpUtility.UrlEncode(dateTimeOffset.ToString("o"));
}