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
-
- The JWT is an encrypted string that has three components - a header, payload, and signature, each separated by a period.
- -The header is the standard configuration for H256.
-
- Header:
- {
- "alg": "HS256",
- "typ": "JWT"
- }
-
-
- 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"
- },
- ...
- ]
- }
-
-
- The supported keys for a URL are as follows:
-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.
- -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>
- )
- 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.
+
+ POST `/api/v1/urls`
+{
+ "urls": [
+ { "url": "https://example.org" },
+ { "url": "https://example.org/1", "keyword": "my-zlink" },
+ {
+ "url": "https://example.org/2",
+ "keyword": "my-zlink2",
+ "collection": "my-collection-name"
}
- ]
- Requests that are sent with invalid tokens, incorrect headers, or invalid access IDs, will be returned with a response of 401 Unauthorized.
- -Thankfully, many JWT libraries do most of the hard work for us -- we just provide the payload and secret key and the library will create the token for us.
-Here’s a full example using Ruby with a JWT library (https://github.com/jwt/ruby-jwt).
-Here, we assume that your Access ID is “12345asdf”, your secret key is “SuperSecretKey”, and you want to create a short URL for the website "http://example.com/fun/site/12345/neat.php"
-
- require 'jwt'
- require 'net/http'
- require 'uri'
+ ],
+}
+ Parameters:
+urls (required) - array of urls to createurls.url (required) - long url of the z-linkurls.keyword - short code which redirects to the urlurls.collection - name of collection to add this url toRequest:
+import jsonwebtoken from "jsonwebtoken";
- access_id = '1234asdf'
- secret_key = 'SuperSecretKey'
+const ACCESS_ID = "my_access_id"; // use your access_id from above
+const SECRET_KEY = "fhRzRyD..."; // use your secret_key from above
- payload = {
- urls: [
- { url: 'http://example.com/fun/site/12345/neat.php' }
- ]
+const payload = {
+ urls: [
+ { url: "https://example.org" },
+ { url: "https://example.org/1", keyword: "my-zlink" },
+ // ...
+ ],
+};
+
+// signing your payload with `SECRET_KEY`
+const signedPayload = jsonwebtoken.sign(payload, SECRET_KEY)
+
+// send the POST request to the server
+const response = await fetch(
+ `https://z.umn.edu/api/v1/urls`,
+ {
+ method: "POST",
+ headers: {
+ Authorization: `${ACCESS_ID}:${signedPayload}`,
+ },
}
+);
- jwt = JWT.encode payload, secret_key, 'HS256'
+const json = await response.json();
+console.log(JSON.stringify(json));
+ Response:
+[{
+ "url": "https://example.org",
+ "result": {
+ "status": "success",
+ "message": "https://z.umn.edu/rd4n3b"
+ },
+},{
+ "url": "https://example.org/1",
+ "keyword": "my-zlink",
+ "result": {
+ "status": "error",
+ "message": ["Keyword has already been taken"]
+ },
+}];PUT `/api/v1/urls/{keyword}`
+{
+ "keyword": "my-zlink",
+ "url": "https://example.org/updated-url"
+}Parameters:
+keyword (required) - short code which redirects to the url. This cannot be updated via API.url (required) - long url of the z-linkRequest:
+import jsonwebtoken from "jsonwebtoken";
- # jwt =
- # eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1cmxzIjpbeyJ1cmwiOiJodHRwOi8vZXhhbXBsZS5jb20vZnVuL3NpdGUvMTIzNDUvbmVhdC5waHAifV19.l8oAAw6SeJgyrE7v65Pxdxz7Yya8UZYCcc3kj5Amieo
+const ACCESS_ID = "my_access_id"; // use your access_id from above
+const SECRET_KEY = "fhRzRyD..."; // use your secret_key from above
- uri = URI('<%= "#{request.base_url}#{api_v1_urls_path}" %>')
+const payload = {
+ keyword: "my-zlink",
+ url: "https://example.org/updated-url"
+};
- Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
- request = Net::HTTP::Post.new uri
- request.add_field('Authorization', "#{access_id}:#{jwt}")
+// sign your payload with `SECRET_KEY`
+const signedPayload = jsonwebtoken.sign(payload, SECRET_KEY)
- response = http.request request
- puts response.body
- end
+// send the POST request to the server
+const response = await fetch(
+ `https://z.umn.edu/api/v1/urls/${payload.keyword}`,
+ {
+ method: "PUT",
+ headers: {
+ Authorization: `${ACCESS_ID}:${signedPayload}`,
+ },
+ }
+);
- Response:
+{
+ "status": "success",
+ "message": {
+ "url": "https://example.org/updated-url",
+ "keyword": "my-zlink",
+ }
+}