| Network Working Group | G. Destiny |
| Internet-Draft | C. Luck |
| Intended status: Informational | Divination Inc. |
| Expires: September 24, 2018 | March 23, 2018 |
An API For Calendar-Based Fortune Heuristics Services
draft-divination-cfapi-00
This document describes a JSON HTTP API for online services that provide calendar-based fortune heuristics.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 24, 2018.
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
Fortune-telling, the practice of predicting information about a person’s life, is an activity practiced throughout history.
While there are myriad forms of fortune telling methodologies, this document applies to a particular form of service that provides fortune heuristics, commonly known as "luck", for a particular subject based on a calendar-based input.
Since HTTP [RFC7230] status codes are insufficient to convey information about fortune heuristics, this specification defines a simple JSON [RFC8259] document format for this purpose. The response can be used by HTTP APIs to deliver results to non-human clients or to an end-user.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The following definitions apply in this document:
A well-known URI called "fortune" is registered by this specification for fortune heuristics services (see Section 10).
Services complying with this document SHOULD have its well-known URI pointing (directly or through redirection) to the Root of Fortune.
The Root of Fortune can be used by the client for service discovery, namely, the available calendar-based fortune heuristics services available on the server, as specified in Section 6.
Servers MUST redirect HTTP requests for that resource to the actual "context path" using one of the available mechanisms provided by HTTP [RFC7230] (e.g., using a 301, 303, or 307 response).
Clients MUST handle HTTP redirects on the well-known URI.
Servers SHOULD set an appropriate Cache-Control header value (as according to Section 5.2 of [RFC7234]) in the redirect response to set caching behavior as required by the type of response generated.
This specification defines two new HTTP methods: "SEEK" and "DIVINE" methods for HTTP [RFC7230].
While HTTP GET requests are treated equivalently as the "SEEK" and "DIVINE" requests, its usage is discouraged and therefore SHOULD NOT be used.
Usage of these methods are defined in the sections below.
This specification defines a number of date-time formats as according to the conventions of [RFC3339] for the unambiguous communication between client and server.
The types defined are as follows.
The Root of Fortune URI, defined as "/" in this document, is used for service discovery on types of calendar-based fortune heuristics available.
An empty SEEK request with the "application/json" request type MUST be sent to this endpoint to retrieve the available endpoints. All other HTTP methods MUST NOT be supported at this URI.
An example of such a response is as follows:
HTTP/1.1 200 Success
Content-Type: application/json
Content-Language: en
{
"diviners" : [
"/astrology",
"/bazi",
]
}
A service discovery object MUST have the following members:
An endpoint offering fortune heuristics services MUST adhere to specifications in this section.
A service MAY implement multiple divination services based on different divination methods, such as the digital oracle shown in Figure 1.
__
__===^-\
__=== -\
__===- -\
__===- -\
___===- -\
===- ---__ -\
\\\ |||^^\ \__ -\
\\\ ||| \__ -\
\\\ ||| ______\_ -\
\\\ ||| _/-******\\__ -\
\\\ || /-****_****-\ \_ -\
\\\ || |-***/ \***-\ \_ -\
\\\ || |-***\___/***-| \ -\
\\\ || \-*********-/ __--/ -\
\\\ || \-******/__-- -\
\\\ || __-- -\
\\\ || __-- -\
\\\ ||__-- -\
\\\ -\
\\\ -\
\\\ -\
\\\ -\
\\\ __ -\
\\\ //##\\ -\
\\\ \\##// -\
\\\ ^^ __--==^
\\\ __--===
\\\ __--===
\\\ __--===
\\\ __--==
\\=
Figure 1: Dimensional Eye, a digital oracle that communicates through one button
To retrieve capabilities and parameters of an endpoint complying with this specification, a service specification JSON object is returned.
An empty SEEK request with the "application/json" request type MUST be sent to this endpoint to retrieve the service specification that describes parameters accepted by this endpoint.
Two examples of such a response are given below.
HTTP/1.1 200 Success
Content-Type: application/json
Content-Language: en
{
"description": "Gaze into your upcoming luck!",
"details": "https://divine.example.com/manual/astrology-api",
"parameters": {
"birthday": {
"type": "DATE",
"description": "Your birth date in UTC"
},
"targetDateBegin": {
"type": "DATE",
"description": "Start of the target date range to report on"
},
"targetDateEnd": {
"type": "DATE",
"description": "End of the target date range to report on"
},
"interval": {
"values": {
"D": "Daily",
"M": "Monthly",
"Y": "Yearly"
},
"description": "Available intervals to report on."
}
}
}
HTTP/1.1 200 Success
Content-Type: application/json
Content-Language: en
{
"description": "Matches and mis-matches according to the "
"Yin Yang and Five Elements techniques",
"details": "https://divine.example.com/manual/bazi-api",
"parameters": {
"birthday": {
"type": "DATETIME",
"description": "Your birth date and time in UTC"
},
"targetDateBegin": {
"type": "DATETIME",
"description": "Start of the target date/time range to report on"
},
"targetDateEnd": {
"type": "DATETIME",
"description": "End of the target date/time range to report on"
},
"interval": {
"values": {
"H": "Hourly",
"D": "Daily",
"M": "Monthly",
"Y": "Yearly"
},
"description": "Available intervals to report on."
}
}
}
A service specification object MUST contain the following members.
A parameter specification object SHOULD contain the following members:
A request using the HTTP "DIVINE" method and the "application/json" type MUST be sent to the fortune heuristic endpoint to retrieve results for a fortune heuristic query.
The request made MUST conform to the specifications of the endpoint, as retrieved via the "SEEK" method described in Section 7.1.
An example of a request is provided below.
URI: /divination/astrology
Method: DIVINE
Content-Type: application/json
Content-Language: en
{
"birthday": "1976-02-11T00:00:00Z",
"targetDateBegin": "2018-01-01T00:00:00Z",
"targetDateEnd": "2019-01-01T00:00:00Z",
"interval": "M"
}
A fortune heuristic query using the "DIVINE" method triggers a response that contains a fortune heuristics report.
A successful response returns a JSON object that MUST conform to the object structure described in this section.
A report object SHOULD contain the following members:
An example of a response is provided below.
URI: /divination/astrology
Method: DIVINE
HTTP/1.1 200 Success
Content-Type: application/json
Content-Language: en
{
"type": "https://association-of.astrology/reports/monthly",
"report": {
"intervals": [
{
"dateStart": "2018-01-01T00:00:00Z",
"dateEnd": "2018-02-01T00:00:00Z",
"categories": [
{
"category":
"https://divine.example.com/astrology/categories/health"
"value": 80,
"description": "Charge ahead with excellent health."
},
{
"category":
"https://divine.example.com/astrology/categories/love"
"value": 70,
"description":
"Give a certain person or situation another try!"
},
{
"category":
"https://divine.example.com/astrology/categories/finance"
"value": 5,
"description": "You've just realized that you don't have
any cash on hand."
}
]
},
{
"dateStart": "2018-02-01T00:00:00Z",
"dateEnd": "2018-03-01T00:00:00Z",
"..."
},
"..."
],
"events": [
{
"dateStart": "2018-01-15T03:20:00",
"dateEnd": "2018-01-16T20:22:15",
"description": "The planet of growth and good luck, Jupiter
will make a harmonious connection with power planet Pluto,
helping you connect with influential people",
"recommendation": "Engage in networking during this time."
},
{
"dateStart": "2018-03-22T00:12:40",
"dateEnd": "2018-03-28T02:45:03",
"description": "Communication planet Mercury enters your sign,
which will find you in a busier and chattier mood.",
"recommendation":
"Take charge of work with your newfound energy."
}
"..."
]
}
}
Fortune heuristic reports are created by a divination output that MAY requires quantitative interpretation. A sample representation of interpreting a graphical divination output is provided in Figure 2.
0000000000000000000000000
0000000000000000000000001 G 1000000000000000000000000
0000000000000000000000011 R 1100000000000000000000000
0000000000000000000000111 A 1110000000000000000000000
0000000000000000000001111 C 1111000000000000000000000
0000000000000000000011111 E 1111100000000000000000000
0000000000000000000111111 , 1111110000000000000000000
0000000000000000001111111 1111111000000000000000000
0000000011111111111111111 M 1111111111111111100000000
0000000111111111111111111 E 1111111111111111110000000
0000001111111111111111111 R 1111111111111111111000000
0000011111111111111111111 C 1111111111111111111100000
0000111111111111111111111 Y 1111111111111111111110000
0001111111111111111111111 , 1111111111111111111111000
0011111111111111111111111 1111111111111111111111100
0111111111111111111111111 A 1111111111111111111111110
0000000000000000011111111 N 1111111100000000000000000
0000000000000000111111111 D 1111111110000000000000000
0000000000000001111111111 1111111111000000000000000
0000000000000011111111111 P 1111111111100000000000000
0000000000000111111111111 E 1111111111110000000000000
0000000000001111111111111 A 1111111111111000000000000
0000000000011111111111111 C 1111111111111100000000000
0000000000111111111111111 E 1111111111111110000000000
0000000001111111111111111 . 1111111111111111000000000
Figure 2: Forty-nine yarrow sticks reveals a mystical message on fortune
The intervals value of a report object contains a number of report intervals — each representing a non-overlapping period of the selected interval length. When all of these intervals are put together, the combined period MUST fully cover the requested report target period.
An example interval object is shown below.
{
"dateStart": "2018-01-01T00:00:00Z",
"dateEnd": "2018-02-01T00:00:00Z",
"categories": [
{
"category":
"https://divine.example.com/astrology/categories/health"
"value": 80,
"description": "Charge ahead with your excellent health."
},
{
"category":
"https://divine.example.com/astrology/categories/love"
"value": 70,
"description": "Give a certain person or situation another try!"
},
{
"category":
"https://divine.example.com/astrology/categories/finance"
"value": 5,
"description": "You've just realized that you don't have
any cash on hand."
}
]
}
An interval object MUST contain the following members:
In the given example, the categories key is an implementation specific object that details heuristic results returned by the selected algorithm. This MAY differ in different algorithms.
The events value of a report object contains a number of event objects. Each event object represents an event relevant to the calculation of fortune heuristics during a target report period. These events MAY be of variable time lengths, and MAY be overlapping amongst each other.
The following example demonstrates two event objects the service determines relevant to a user’s query.
{
"dateStart": "2018-01-15T03:20:00",
"dateEnd": "2018-01-16T20:22:15",
"description": "The planet of growth and good luck, Jupiter will
make a harmonious connection with power planet Pluto, helping you
connect with influential people",
"recommendation": "Engage in networking during this time."
},
{
"dateStart": "2018-03-22T00:12:40",
"dateEnd": "2018-03-28T02:45:03",
"description": "Communication planet Mercury enters your sign,
which will find you in a busier and chattier mood.",
"recommendation": "Take charge of work with your newfound energy."
}
Similar to an interval object, an event object MUST contain the following members:
In the given example, the keys description and recommendation are implementation-specific details. This MAY differ in different algorithms.
This specification makes use of normal HTTP error codes with the following extensions.
Errors MUST be returned using the Problem JSON Structure as accordance with [RFC7807].
This document defines a well-known URI using the registration procedure and template from Section 5.1 of [RFC5785].
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC5785] | Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, April 2010. |
| [RFC7230] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014. |
| [RFC7234] | Fielding, R., Nottingham, M. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Caching", RFC 7234, DOI 10.17487/RFC7234, June 2014. |
| [RFC7807] | Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016. |
| [RFC8174] | Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017. |
| [RFC8259] | Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017. |
| [ISO.8601-1.2018] | ISO/IEC, "ISO/DIS 8601-1:2018, Data elements and interchange formats -- Information interchange -- Representation of dates and times -- Part 1: Basic rules", January 2018. |
| [RFC3339] | Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. |
| [RFC5246] | Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008. |
The authors thank the following individuals for their valuable feedback on this specification, and commend them for making fortune heuristics more accessible for the benefit of mankind.