From fc03cb4614179ce9b50a40e029bb7e17935cd66e Mon Sep 17 00:00:00 2001 From: James Johnson Date: Tue, 14 May 2024 09:38:51 -0500 Subject: [PATCH] Update Z api docs (#167) --- app/views/api_keys/index.html.erb | 310 +++++++++++++------------ app/views/layouts/application.html.erb | 2 +- 2 files changed, 163 insertions(+), 149 deletions(-) diff --git a/app/views/api_keys/index.html.erb b/app/views/api_keys/index.html.erb index 80842f7e..abe56374 100644 --- a/app/views/api_keys/index.html.erb +++ b/app/views/api_keys/index.html.erb @@ -2,167 +2,181 @@ <%= t('views.api_keys.index.title') %> <% end %>
-
-
-
-
-
Access ID
-
- <%= current_user.uid %> +
+ +
+
+
+

Using the Z Api

+
+
+
+
Access ID
+
+ <%= current_user.uid %> +
-
-
-
Secret Key
-
- <%= current_user.secret_key %> - <%= link_to api_keys_path, method: :post, class: 'btn btn-default clipboard-btn' do %> - - Generate new key - <% end %> +
+
Secret Key
+
+ <%= current_user.secret_key %> + <%= link_to api_keys_path, method: :post, class: 'btn btn-default clipboard-btn' do %> + + Generate new key + <% end %> +
-
-

Z features an API to allow Short URL creation directly from your applications.

-

The API is configured to use JSON Web Tokens (or JWT, https://jwt.io) to ensure secure communications between the client and server. This is a popular method that has libraries for most popular programming languages. See their website for specific language support.

-

Z has one API endpoint, <%= "#{request.base_url}#{api_v1_urls_path}" %>. You can POST to this endpoint with your Access ID and the JWT (signed by your secret key), separated by a colon in an Authorization Header, like so:

- 
-  Header Name: Authorization
-  Header Value: access_id:jwt
-
- - -

Token Information

-
-

The JWT is an encrypted string that has three components - a header, payload, and signature, each separated by a period.

- -

Header

-
-

The header is the standard configuration for H256.

- 
-  Header:
-  {
-    "alg": "HS256",
-    "typ": "JWT"
-  }
-
- -

Payload

-
-

The payload is a single JSON object, containing one key, “urls”. This key contains an array of JSON objects for each URL you would like created. Example:

- 
-  Payload:
-  {
-    "urls": [
-      { "url": "http://google.com", },
-      {
-        "url": "http://example.com/internet",
-        "keyword": "einter"
-      },
-      ...
-    ]
-  }
-
- -

Supported keys

-

The supported keys for a URL are as follows:

-
    -
  • "url" : The URL you would like shortened (required)
    • -
  • "keyword" : The keyword you would prefer (optional)
    • -
  • "collection" : The collection name you would like this URL to be placed into. (optional).
    • -
-

If no keyword or collection are specified, Z will auto-generate a short URL for you. If the “keyword” you request is already taken, the URL will not be created. If a “collection” name cannot be found, the URL will not be created.

- -

Signature

-
-

The final signature is an encoded string containing the header, the payload, and signed with your secret key.

- 
Signature:
-  HMACSHA256(
-    base64UrlEncode(header) + "." +
-    base64UrlEncode(payload),
-    <secret_key>
-  )
-
- -

Return values

-
-

Upon sending the request, the you can expect the response to be an array of JSON objects, with each item containing the original URL data from the request, as well as a result object that contains two items.

-

The first result key is “status”, which will either be “success” or “error”.

-

The second result key is “message”, which will either contain a string with the new Short URL for your item, or an array of errors returned by the system.

- 
-  Result:
-  [
-    {
-      "url": 'http://google.com',
-      "result":
-        {
-          "status": 'success',
-          "message": 'http://localhost:3000/2siu'
-        }
-    },
-    {
-      "url": 'http://example.com/internet',
-      "keyword": 'einter',
-      "result":
-        {
-          "status": 'error',
-          "message": [
-            'Keyword has already been taken.'
-          ]
-        }
+        
Z features an API for creating and updating directly from your applications.

+        

+          Each API request must have an http Authorization header with your Access ID (above) and a payload signed with your Secret Key (above) in the form of a JSON Web Token (or JWT). The access id and signed payload are separated by a colon :.
+        

+        
Authorization: {your_access_id}:{your_signed_payload}

+        

+          To create your signed payload, use a JWT library for your programming language.  
+        

+        

+          The examples below use JavaScript and the jsonwebtoken library. You can also find an example implementation on Github.
+        

+
+ +
diff --git a/app/views/layouts/application.html.erb b/app/views/layouts/application.html.erb index 4616fa9b..13d00eed 100644 --- a/app/views/layouts/application.html.erb +++ b/app/views/layouts/application.html.erb @@ -33,7 +33,7 @@ <%= yield %>
- +