What is the 'api_key' and how do I use it correctly

Question

I'm fairly new to restful services, and I've just implemented the test code to get a ServiceStack restful service going with the Swagger plugin working as well, which leads me to my question...

inside swagger-ui/index.html there is a field for 'api_key'. I know the variable name is umm... variable, and I can set it too whatever I like, but I'm slightly confused what it's used for and whether I should be making use of it.

Also, if I do use it, how does servicestack present that value to me on the server side?

Here is the Test Service I've got up and running from the documentation...

    [Api("Hello Web Services")]    
    [Route("/Hello", Summary = @"Noel's ServiceStackSwagger thingy", Notes = "Some more info in here cause these are notes")]
    [Route("/Hello/{name}",   Summary = @"N031'5 ServiceStackSwagger thingy", Notes = "Some more info in here cause these are notes", Verbs="GET,POST" )] 
    public class Hello
    {
        [ApiMember(Name = "Name", Description = "This is a description", ParameterType = "path", DataType = "string", Verb="GET,POST")]
        public string Name { get; set; }
    }

    public class HelloResponse
    {
        public string Result { get; set; }
    }


    public class HelloService : Service
    {
        public object Any(Hello request)
        {
            return new HelloResponse { Result = "Hello, " + request.Name };
        }
    }

Solution 1

to answer my own follow up request of Esker, here is how to use the API Key thingy...

public class HelloService : Service
{        
    public object Any(Hello request)        
    {
        string api_key = this.Request.Headers["api_key"];            
        return new HelloResponse { Result = "Hello, " + request.Name };
    }
} 

but also required is some extra javascript to include it in the header like so (inside swagger-ui/index.html)...

   $(function () {
        $.ajaxSetup({
            beforeSend: function (jqXHR, settings) {
                jqXHR.setRequestHeader("api_key", $("#input_apiKey").val());
            }
        });
    });

which I found in an answer in this question...

How to get Swagger to send API key as a http instead of in the URL

Solution 2

Swagger UI has a general concept of supplying an api_key to use in every request sent to your service, documented here. It can either be sent as a query string or header value, and you can also change the name of the parameter as described in the above link.

You only need to configure this if you actually do require an API key in your ServiceStack service (e.g. if you have a request filter that checks for and validates an API key, perhaps).

The reason you might need to configure a default API key value in the JavaScript code to set up Swagger instead of having the user type in an API key is that as soon the index.html page loads, it will send multiple requests to your service to retrieve the metadata, so it wants to know what API key value to send by default for these metadata requests before the user can begin to interact.

Comments

[Mike Mertsock]

Not related to your question, but note that you can have the Hello class implement the IReturn interface to make your service even more self-documenting, and make it easier to work with the ServiceStack typed C# client: class Hello : IReturn<HelloResponse> ...