Technical Groundwork

Modified on:: Mon, 31 May, 2021 at 1:59 PM

Print


TABLE OF CONTENTS


HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.


Verb
Description
OPTIONS
The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval. (Ref: Link)
HEAD
The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. This method can be used for obtaining meta information about the entity implied by the request without transferring the entity-body itself. 

GET
Used for retrieving resources.
POST
Used for creating resources.
PUT
Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE
Used for deleting resources.


HTTP Response Codes

For the http communication, we rely on the standard response codes used. An extensive list can be found for example here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status (external site, PRISMA is not responsible for the content shown there). Please be aware that we do not use all of the displayed codes, but they give you a better understanding, when you run into one of them.


Schema & Timestamps

All API access is over HTTPS. All data is sent and received as JSON.


Example of a query for your companies' auction bookings:

curl --location --request GET 'https://platform.kon.prisma-capacity.cloud/api/v2/auction-booking' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YourBearerCodeHere' \



Blank fields are included as null instead of being omitted.

All timestamps in the body are returned as ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Some requests require for specifying timestamps or generate timestamps with time zone information. We apply the following rule to handle time zone information for API calls:

For API calls that allow for a timestamp to be specified, we use the exact timestamp, specified in UTC time.

These timestamps look something like 2021-04-27T04:00:00.000Z

 

Summary representations

When a list of resources is fetched, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource.
Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the "detailed" representation, such as a complete list of auction details (via GET .../auction/{id}) and not just basic auction information (which is provided with the GET .../auction query).


Detailed representations

When an individual resource is fetched, the response typically includes all attributes for that resource. This is the "detailed" representation of the resource.
(Note that authorization can influence the amount of detail included in the representation.)


Example: When you get an individual auction, you get the detailed representation of the auction. Here, we fetch the details of auction ID 20213254:

curl -X GET "https://platform.kon.prisma-capacity.cloud/api/v2/auction/20213254" -H  "accept: application/json"

The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl -X GET "https://platform.kon.prisma-capacity.cloud/api/v2/auction?periodType=MONTH&state=OPEN"


In this example, the 'api' and 'v2' values are provided for the :owner and :repo parameters in the path while :periodType and :state are passed in the query string.


For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json':

curl -X POST "https://platform.kon.prisma-capacity.cloud/api/v2/bid" 
-H "accept: application/json" 
-H "content-type: application/json" 
-d "{
        \"auctionId\": 0,
        \"balancingGroupIdExit\": THE1234567890,
        \"userEmail\": \"test@email.test\",
        \"surcharge\": 
        {
          \"value\": \"1.3523\",
          \"unit\":
          {      
            \"currency\": \"EUR\",
            \"subunit\": true,
            \"quantityUnit\": \"K_WH_H\",
            \"priceRuntime\": \"HOUR\"
          }
        }, 
       \"capacityQuantity\": 
        {
          \"value\": 1000,    
          \"unit\": \"K_WH_H\"
        }, 
       \"minimumQuantity\": 
       {
        \"value\": 1,    
        \"unit\": \"K_WH_H\"
       },  
      \"gtcAccepted\": true,
    }
 }"


Rate Limit

For requests using the PRISMA API, you can make up to 200 requests per 60 seconds. Authenticated requests are associated with the authenticated user. In the response header the current applicable limit (X-RateLimit-Limit) and the number of your remaining calls are contained (X-RateLimit-Remaining). Also, you will find there the reference to the point in time, when your rate limit is reset (X-RateLimit-Reset). The timestamp is transmitted as Unix-Time in Milliseconds.


X-RateLimit-Limit : 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 1622451084108


Hypermedia 

All resources may have one or more "href" properties linking to other resources. These are meant to provide explicit URLs so that API clients don't need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for your developers. 


Also, resources that return summary responses, will contain one "self" property. This property allows you to request the detailed response of this item. 


Below is an example entry of the response to "GET .../tso" request. This response is a summary response: 

{
        "id": 1,
        "name": "Gastransport Nord GmbH",
        "eic": "21X000000001132G",
        "marketAreas": [
            {
                "id": 1,
                "name": "L-Gas 1",
                "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/1"
            },
            {
                "id": 2,
                "name": "GASPOOL",
                "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/2"
            },
            {
                "id": 3,
                "name": "NetConnect Germany",
                "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/3"
            },
            {
                "id": 196608,
                "name": "Trading Hub Europe",
                "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/196608"
            }
        ],
        "self": "https://platform.test.prisma-capacity.cloud:443/api/v2/tso/1"
    },


For requesting details of this TSO, your client can request "GET .../tso/1". You would receive this response:


{
    "id": 1,
    "name": "Gastransport Nord GmbH",
    "shortName": "GTG-TEST1",
    "eic": "21X000000001132G",
    "gtcUrl": "http://www.gtg-nord.de/en/downloads.php",
    "address": {
        "street": "Street",
        "zipCode": "00000",
        "city": "Oldenburg",
        "countryCode": "DE",
        "poBox": "7308",
        "poBoxZipCode": "16252",
        "poBoxCity": "Rümmingen"
    },
    "communication": {
        "phone": "+4944112345",
        "phoneBackup": "3343344990",
        "phoneOnCall": "5401165918",
        "mobile": "3505381198",
        "fax": "+4944111122"
    },
    "url": "https://gtg-nord.de/de/",
    "contactFormUrl": "https://gtg-nord.de/de/download.php?dwn=43",
    "requiredTsoSpecificIdList": [
        "EIC"
    ],
    "contractingServicesList": [
        {
            "id": 851968,
            "serviceLabel": "Conversion Unbundled to Bundled",
            "serviceEmail": "netznutzung@gtg-nord.de",
            "fieldLabels": [
                "Unbundled Contract ID",
                "Period Start",
                "Period End",
                "Quantity",
                "Bundled Deal ID"
            ],
            "enabled": true
        }
    ],
    "fcfsLeadTimeHint": "<h6>The conclusion of contracts for entry- and exit-capacity is subject to constraints depending on the contract runtime. Contracts with a runtime</h6><br>\n<ul><p>\n<li>equal or longer than one year may be concluded anytime.\n<li>of one quarter and starting on October 1st, January 1st, April 1st or July 1st may be concluded the earliest on the day of the start of the first yearly auction for quarterly capacity. The date is published on the capacity booking platform.\n<li>of less than a year but not matching to a quarterly product may be concluded the earliest three month prior to the start of the contract runtime.\n<li>of less than a month may be concluded the earliest one month prior to the start of the contract runtime.\n<li>of one gas day may be concluded the earliest one month prior to the start of the contract runtime and at the latest three hours prior to the start of the contract runtime.</li>\n<ul>\n<li>Contracts concluded prior to 6 p.m. on the day before the contract runtime start are considered as day ahead contracts. All contracts concluded after this deadline are considered as rest of the day contracts.</ul>\n<li>of less than one gas day may be concluded \n<ul>\n<li>at exit points to final consumers, the earliest two hours prior the start of the contract runtime and at the latest one hour prior the start of the contract runtime.\n<li>[valid until March 31st 2018] at entry and exit points to storage facilities the earliest four hours prior to the start of the contract runtime and the at latest three hours to the start of the contract runtime.</p><br>",
    "marketAreas": [
        {
            "id": 1,
            "name": "L-Gas 1",
            "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/1"
        },
        {
            "id": 2,
            "name": "GASPOOL",
            "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/2"
        },
        {
            "id": 3,
            "name": "NetConnect Germany",
            "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/3"
        },
        {
            "id": 196608,
            "name": "Trading Hub Europe",
            "href": "https://platform.test.prisma-capacity.cloud:443/api/v2/market-area/196608"
        }
    ],
    "currency": "EUR",
    "self": "https://platform.test.prisma-capacity.cloud:443/api/v2/tso/1"
}




M
Maryam is the author of this solution article.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.