Usage scenarios or usage instructions to Api details page

[bajiat]

Include simple usage instructions or common usage instructions to API details page. These instructions should contain a possibility to copy at least user's API key (if an API key is available and if a proxy has been selected to this particular API)

User story

As an API consumer
I want to be able to quickly find out how to use the API I'm interested in through APInf
so that I do not have to find the information from several different places

Definition of done

• Select what would be the two most common / relevant methods of making api calls
  • url parameter - with ?api_key=### query parameter
  • request header - passing in X-Api-Key as a request header
• Document the methods in user instructions
• Add the usage instructions to the API profile view (Details tab)
• Auto-insert e.g. base URL and user's API key. (API key only if a proxy has been selected)
• Allow copying base URL and user's API key, if available.

Wireframe

[philippeluickx]

Concretely, some information about development.
I am using Android as an example here, with Retrofit the de-facto REST library - https://github.com/square/retrofit

OkHttpClient client = new OkHttpClient();

client.interceptors().add(new Interceptor() {
    @Override
    public Response intercept(Chain chain) throws IOException {
        Request request = chain.request();
        HttpUrl url = request.url().newBuilder().addQueryParameter("api_key","XYZ123").build();
        request = request.newBuilder().url(url).build();
        return chain.proceed(request);
    }
});

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("CLIENT.apinf.io")
        .client(client)
        .build();




public interface SpaceshipsService {
  @GET("spaceships")
  Call<List<Spaceship>> listSpaceships();
}

The relevant places are

The base url

.baseUrl("CLIENT.apinf.io")

The api-key parameter added to every request

HttpUrl url = request.url().newBuilder().addQueryParameter("api_key","XYZ123").build();

The actual call to an endpoint, as defined in Swagger

  @GET("spaceships")

As an Android developer, the first 2 items is what I need for configuration and I find this in detail or settings somewhere. The third item I find that in documentation.

[Nazarah]

@NNN : what are your ideas about the possible UI view? please let me know.

[Nazarah]

@NNN Based on our discussion, I prepared the given wireframe.
Please make suggestions about possible changes in the look&feel or description text.

[bajiat]

@NNN What is the status of this task?

[55]

@bajiat PR is ready for review.
I have removed all instruction text because I think it's not need here at all.
All usage instruction can be placed by owner at a) description field b) documentation tab.
Added test call button, which is shown if proxy is selected and API key is available.
Helper constructs test call URL from BaseUrl + ?api_key= + API key.

[brylie]

I have removed all instruction text because I think it's not need here at all.
All usage instruction can be placed by owner at a) description field b) documentation tab.
-- @NNN

The instruction text is an important part of this task. We want to give brief instructions on how to call the API in the following ways:

• url parameter - using proxy URL or API url
  • if proxy url: append the base path + user api_key query parameter
• request header - an example of making a request using X-Api-Key as a header

Be sure to refer to the API Umbrella documentation for an example of how to make a post call.

Ping: @bajiat @preriasusi: does this seem correct to you?

[brylie]

Added test call button, which is shown if proxy is selected and API key is available.
-- @NNN

There is no need for a 'try it out' button here. The task is only to create usage instructions.

Ping: @bajiat @preriasusi

[brylie]

I am using Android as an example here, with Retrofit the de-facto REST library
-- @philippeluickx

For simplicity, we are only covering standard GET/POST requests. I.e. we will not provide language/framework specific usage examples.

[preriasusi]

I agree with @brylie. This instruction text should tell basic info how to call api. When arrives to api page for the first time, he/she finds the url of the api. He/she should also know how can he/she call the api, meaning how to give API key. The endpoints, test calls and code examples/snippets should go to documentation tab.

[55]

@bajiat, @preriasusi, @brylie got it. Working on it.

[bajiat]

Agree with the comments above. This is just user instructions, and should not contain functionality to call the API (ie. Try out button), because the base URL should not return anything.
It should be enough to describe how to use the API key in context with this API. Also, would select one of the methods, perhaps using API key in the header, if that is the more secure way to pass the key.

[brylie]

Help text could, for instance, say:

To make calls to this API, you can either:

• call the API with your key in the URL parameters:
  • https://<host>/<base_path>?api_key=<user_api_key>
• call the API with your key in the request headers
  • X-Api-Key: <user_api_key>

We can refine the text, but this is the basic pattern.

Ping @bajiat @Nazarah @preriasusi

[preriasusi]

That should do it.

[philippeluickx]

Are we using the correct terminology here?
Let's say https://maps.google.com/api/v1/locations/finland?api_key=123

host = maps.google.com or maps.google.com/api/v1 ?
? = /api/v1
base path = /api/v1/locations/finland or just /locations/finland ? (or is this called endpoint?)

Based on Mozilla, there is other terminology
https:// = protocol
maps.google.com = Domain name
/api/v1/locations/finland = path

Based on Apigee the terminology becomes
maps.google.com/api/v1 = base path
/locations/finland = resource

[brylie]

'Host' and 'basePath' come from the Open API Specification:

host (string) The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port.

basePath (string) The base path on which the API is served, which is relative to the host.

[brylie]

Terminology aside, the <host>, <base_path>, and <user_api_key> placeholders should be replaced with actual values, specific to the Proxy (host), ProxyBackend (frontend prefix), and user (API key).

[philippeluickx]

Ok, Open API specs are a good ref indeed.
However, after the base_path you would still need something like the "resources" as Apigee calls it? I consider the base_path as being the /api/v1 part (I could be wrong of course)

[brylie]

I mixed up the terminology, as there are quite a lot of similar words/concepts.

The frontend_prefix comes from API Umbrella, and is part of our ProxyBackend.apiUmbrellaSchema.

Basically, we want to construct a URL for the end user with the following structure:

http(s):// <proxy_host> / <frontend_prefix> /? <user_api_key>

[brylie]

The current work on the usage instructions looks nice:

However, we are still missing key points in the definition of done.

Please provide a valid URL in the usage instructions, with actual values for:

• host (API Umbrella url)
• frontend prefix (proxy backend: API Umbrella frontend prefix)
• user api key (if available, from the ApiKeys collection: API Umbrella key)