.. _slicing-service-reference:

API Reference
=============

Authentise's Slicing Service was built to enable tool-path generation in the cloud.

There are a few concepts involved with the Slicing Service.
Its designed to be used in tandem with the Model Warehouse. The Slicing Service boasts two resources of its own: configs, and slices. A slice resource takes a config, and a model resource.

.. http:post:: /config/curated/

    Create a new config resource with our curated list of parameters. Our engineers broke out these settings, as they make the most obvious changes in a config.

    :<json string engine: **Required.** the slicing engine you want to use. Current options include ``slic3r`` and ``makerbot``.
    :<json string description: **Optional.** The name of the config. This can be any string and should be meaningful to the user.
    :<json object parameters: **Optional.** A list of curated options that most users stick to, some more advanced than others.
    :<json string parameters.material: ``ABS`` or ``PLA``.
    :<json string parameters.print_quality: ``fine`` (0.1mm), ``low`` (0.3mm), or ``standard`` (0.2mm).
    :<json float parameters.filament_diameter: The filament diameter that works with your machine in millimeters.
    :<json float parameters.nozzle_diameter: The nozzle diameter that works with your machine in millimeters.
    :<json float parameters.infill_density: Sets the inside density of a print.
    :<json float parameters.infill_speed: Sets the speed of the printer when its printing the infill.
    :<json float parameters.extruder_temperature: Sets the temperature of the print nozzle.
    :<json float parameters.bed_temperature: Sets the temperature of the heated bed.
    :<json int parameters.perimeters: Sets the number of perimeters of a print.
    :<json float parameters.perimeter_speed: Sets the speed of the printer when its printing the perimeters.
    :<json bool parameters.support: Turns on, or off the support feature.
    :<json bool parameters.raft: turns on, or off the raft feature.

    **Example request**

    .. sourcecode:: javascript

        {
            "description": "makerbot high-resolution",
            "engine": "makerbot",
            "parameters": {"material": "ABS",
                       "print_quality": "fine",
                       "filament_diameter": 1.75,
                       "nozzle_diameter": 0.4
                       "infill_density": 33.0,
                       "infill_speed": 90.0,
                       "extruder_temperature": 240.0,
                       "bed_temperature": 110.0,
                       "perimeters": 2,
                       "perimeter_speed": 40.0,
                       "support": false,
                       "raft": false
            }
        }

    :>header Location: The URI of the model where information about the config can be requested. Ex: `/config/<uuid>/`

.. http:post:: /config/raw/

    Create a new config resource using the raw contents of a pre-existing config file.

    :<json string engine: **Required.** the slicing engine you want to use. Current options include ``slic3r`` and ``makerbot``.
    :<json string content: **Required.** the contents of a config file as a string.
    :<json string description: **Optional.** The name of the config. This can be any string and should be meaningful to the user.

    **Example request**

    .. sourcecode:: javascript

        {
            "description": "makerbot high-resolution",
            "engine": "makerbot",
            "content": {"avoid_crossing_perimeters = 0\nbed_size = 200,200\nbed_temperature = 0\nbottom_solid_layers = 3\nbridge_acceleration = 0\n....."
            }
        }

    :>header Location: The URI of the model where information about the config can be requested. Ex: `/config/<uuid>/`

.. http:get:: /config/<uuid>/

    Get information about a config. Each parameter that was populated in ``/config/curated/`` will be populated, otherwise those properties will be null.

    :>json string description: The user defined description of the configuration.
    :>json string engine: The name of the engine this config corresponds to.
    :>json string content: The url of a link at which the config can be downloaded.
    :>json object parameters: A list of curated options that most users stick to, some more advanced than others.
    :>json string parameters.material: ``ABS`` or ``PLA``.
    :>json string parameters.print_quality: ``fine`` (0.1mm), ``low`` (0.3mm), or ``standard`` (0.2mm).
    :>json float parameters.filament_diameter: The filament diameter that works with your machine in millimeters.
    :>json float parameters.nozzle_diameter: The nozzle diameter that works with your machine in millimeters.
    :>json float parameters.infill_density: Sets the inside density of a print.
    :>json float parameters.infill_speed: Sets the speed of the printer when its printing the infill.
    :>json float parameters.extruder_temperature: Sets the temperature of the print nozzle.
    :>json float parameters.bed_temperature: Sets the temperature of the heated bed.
    :>json int parameters.perimeters: Sets the number of perimeters of a print.
    :>json float parameters.perimeter_speed: Sets the speed of the printer when its printing the perimeters.
    :>json bool parameters.support: Turns on, or off the support feature.
    :>json bool parameters.raft: turns on, or off the raft feature.

.. http:post:: /constraint/

    Create a new config constraint resource with the curated list of parameters.

    :<json string name: **Required.** the config constraint name that you want to use.
    :<json string description: **Optional.** The description of the config constraint. This can be any string and should be meaningful to the user.
    :<json object parameters: **Required.** A list of curated options that will be applied to a slicing config.
    :>json object parameters.material: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.print_quality: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.filament_diameter: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.nozzle_diameter: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.infill_density: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.infill_speed: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.extruder_temperature: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.bed_temperature: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.perimeters: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.perimeter_speed: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.support: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.
    :>json object parameters.raft: ``_in``, ``equals``, ``min``, ``max``, ``not-equals-to``.

    **Example request**

    .. sourcecode:: javascript

        {
            "name": "High Quality",
            "description": "Slicing config constraint that ensures high quality prints",
            "parameters": {
                "material": {
                    "_in" ["ABS", "PLA"]
                },
                "print_quality": {
                    "equals": "fine"
                },
                "extruder_temperature": {
                    "not-equals-to": 240.0
                },
                "filament_diameter": {
                    "min": 1.75
                },
                "nozzle_diameter": {
                    "max": 0.4
                },
                "infill_density": {
                    "less-than": 33.0
                },
                "infill_speed": {
                    "greater-than": 90.0
                }
            }
        }

    :>header Location: The URI of the constraint config where information about the constraint config can be requested. Ex: `/constraint/<uuid>/`

.. http:get:: /constraint/<uuid>/

    Get information about a config constraint.

    :<json string name: The config constraint name that you want to use.
    :<json string description: The description of the config constraint. This can be any string and should be meaningful to the user.
    :<json object parameters: A list of curated options that will be applied to a slicing config.

.. http:put:: /constraint/<uuid>/

    Update a config constraint.

    :<json string name: The config constraint name that you want to use.
    :<json string description: The description of the config constraint. This can be any string and should be meaningful to the user.

.. http:delete:: /constraint/<uuid>/

    Delete a config constraint.

.. http:post:: /constraint-model/

    Associate a config constraint with a model

    :<json string constraint: **Required.** The uri of constraint config to associate with.
    :<json string model_uri: **Required.** The model uri to associate the constraint config with.

    **Example request**

    .. sourcecode:: javascript

        {
            "constraint": "https://quickslice.authentise.com/constraint/319f9c7f-f955-434e-b382-4c7f32ce131a/",
            "model_uri": "httos://hoth.authentise.com/model/ed6820b4-e16f-4127-8eae-8195896ed0e5/"
        }

    :>header Location: The URI of the constraint model where information about the constraint model can be requested. Ex: `/constraint-model/<uuid>/`

.. http:get:: /constraint-model/<uuid>/

    Get information about a constraint model.

    :<json string constraint: The uri of constraint config.
    :<json string model_uri: The model uri.

.. http:delete:: /constraint/<uuid>/

    Delete a constraint model

.. http:post:: /slice/

    Create a new slice job. A slice job is rather basic; given a model resource and a config resource (assuming neither of them are in error), will simply kick off a slice job.

    If the optional callback parameters are included, we will notify you when the status changes Ex: processing, processed, and/or error.

    If the slicing config conflicts with a constraint applied to the model then the slicing will not proceed and the response will return status code 409 with details about the issue.

    :<json string model: **Required.** The location of the model resource you want to slice.
    :<json string config: **Required.** The location of the config resource you want to slice the model with.

    :<json obj callback: **Optional**. The URL to call when this slice job changes states.
    :<json string callback.url: **Optional**. The URL to request for the callback
    :<json string callback.method: **Optional**. The method to use for the request, one of GET, POST or PUT.

    **Example request**

    .. sourcecode:: javascript

        {
            "model": "https://models.authentise.com/model/abc-123/",
            "config": "https://slice.authentise.com/config/def-456/",
            "callback": {"url": "mysite.com/callback", "method": "POST"}
        }

    :>header Location: The URI of the model where information about the slice operation can be requested. Ex: `/slice/ghi-789/`

.. http:get:: /slice/<uuid>/

    Get information about a slice.

    :>json string status: The current status of the slice. Can be one of ``queued``, ``processing``, ``processed``, or ``error``.
    :>json string config: The url of the config resource that was used to create this slice job
    :>json string content: The url of a link at which the finished slice can be downloaded, if the slice has finished, and was successful.
    :>json int slice_time: render time, in seconds. This property will only be populated if the slice has finished, and was successful.
    :>json object estimates: Object that provides useful estimates about a print
    :>json float estimates.build_time_seconds: Estimated build time. Only available when slicing with CatalystEx.
    :>json float estimates.support_volume_cc: Support volume in cubic centimeters. Only available when slicing with CatalystEx.
    :>json float estimates.build_volume_cc: Build volume in cubic centimeters. Only available when slicing with CatalystEx.

.. http:post:: /gcode/

    Create a new gcode.

    :<json string name: **Optional.** The gcode name

    **Example request**

    .. sourcecode:: javascript

        {
            "name": "3mm Cube gcode"
        }

    :>header Location: The URI of the gcode where information about the gcode can be requested. Ex: `/gcode/ghi-299/`
    :>header X-Upload-Location: The URI to upload the gcode contents to.

.. http:get:: /gcode/<uuid>/

    Get information about a gcode.

    :>json string name: The name of the gcode.
    :>json status: The current status of the gcode. Can be one of ``not-uploaded``, ``processing``, ``processed``, or ``error``.
    :>json string content: The URL of a link at which the gcode can be downloaded, if the gcode has been processed, and was successfully validated.