A Starting Design for the Endpoints

This is a more general overlook about the API’s endpoints. The implementation described here is the application of the use-case no.2 described here in issue #2 .

For the use-case no.2, the demo API we are going to develop is about Commercial Off The Shelves (COTS) spare parts for pico- and nano-satellites. Has been a recent trend in commercial space industry to develop super-light and super-compact satellites for the sake of research, prototyping, Earth observation and product testing.

The kind of parts we are talking about are basically microcontrollers and processors that allows the spacecraft to operate. Each of these “boards” is meant to provide a function; there are 8-9 different functions (subsystems) to be carried on for the spacecraft to accomplish its mission. Some of them are critical, some other are supporting functions but likely almost every spacecraft needs almost all of them to work properly. This is a comprehensive list as they are written in the “subsystems” vocabulary:

• propulsion
• primary power
• backup power
• thermal active
• thermal passive
• structure
• command and data handling
• communication
• attitude and navigation (AODCS) active or passive

This API will serve objects related to this kind of hardware. The simple starting endpoints can be:

• /api/cots/: from which the single hardware parts are store and retrieved. In particular:
  • GET /api/cots/<id> to fetch a particular object,
  • PUT /api/cots/<id> to store a new object with some characteristics
  • PATCH /api/cots/<id>: only for some properties
  • DELETE /api/cots/<id>

Mandatory fields for every category of subsystem are specified in the vocabulary itself. An example of COTS spare part is represented by this JSON, this is a backup power subsystem:

{
    "id": 1, 
    "object": {
        "category": "backup power", 
        "maxWorkingTemp": 61, 
        "volume": 126, 
        "minWorkingTemp": -21, 
        "mass": 252, 
        "power": 638, 
        "cost": 10208
    }, 
    "name": "2KV backup power",
    "year": "2015",
    "manufacturer": "Invented Corp."
}

This JSON is ported into a JSON-LD using this two vocabularies: one for the spacecraft, one for different subsystems :

{ 
    "@context": {
        "spacecraft"  : "http://ontology.projectchronos.eu/spacecraft/",
        "subsystems"  : "http://ontology.projectchronos.eu/subsystems/"
    },
    "@id": "/api/cots/1",
    "@type": "spacecraft:Subsystem_Spacecraft",
    "subsystems:subSystemType": "subsystems:Spacecraft_BackupPower",
    "subsystems:function": "Backup and restore energy if Power no. 1 goes down",
    "subsystems:isStandard": "Cubesat",
    "subsystems:maxWorkingTemp": 61, 
    "subsystems:volume": 126, 
    "subsystems:minWorkingTemp": -21, 
    "subsystems:mass": 252, 
    "subsystems:power": 638, 
    "subsystems:cost": 10208,
    "subsystems:manufacturer": "Invented Corp."
    }, 
    "skos:name": "2KV backup power",
    "subsystems:year": "2015"
}

• /api/spacecraft/<id>: an assembled group of COTS that can be used to make up an actual satellite. Each COTS object is categorized into a group that represents its function. For this endpoint:
  • GET /api/spacecraft/<id>: retrieve a blueprint
  • PUT /api/spacecraft/<id>: create a new blueprint
  • PATCH /api/spacecraft/<id>: emend some component of the blueprint
  • DELETE /api/spacecraft/<id>: remove ablueprint As for the subsytem objects above a JSON and a JSON-LD desctiption will be provided.

These are the endpoints that need to be served by the server with the proper description provided using the HYDRA framework.

[chrizandr]

As applications for GSoC have started, here is a document I wrote regarding possible solutions and other specifications for the design. Your feedback and views are highly appreciated. The document allows comments so please feel free to write your suggestions

https://docs.google.com/document/d/1YjGPwoIQh9af3OdppSBmCHaEAez8kMRy-9F9WXttQiw/edit?usp=sharing

I will write the final proposal once I get feedback from mentors on this document.

Looking forward to working with you,

Regards,

[pchampin]

Should it go strictly follow the REST constrains including HATEOAS, or apply flexibly?

PUT to create resources does not contradict REST nor HATEOAS.

For creating a new object, I prefer using POST (user specified ID could be contained in the post data body),

Specifying the ID in the POST body is indeed possible, but not standard, so it increases the coupling between the client and the server (note that the Slug header from the Atom protocol can still be used to suggest and ID, but not specifiy it).

since when doing a PUT to /objects/, the target object should be already existed.

Nothing in the definition of PUT imposes that.