api-design

API Design Skill

REST API design for Nav services. Covers naming conventions, error handling with ProblemDetail, versioning, pagination, and OpenAPI spec.

URL Conventions

# ✅ Correct
GET    /api/vedtak                    # List
GET    /api/vedtak/{id}               # Get by ID
POST   /api/vedtak                    # Create
PUT    /api/vedtak/{id}               # Full update
PATCH  /api/vedtak/{id}               # Partial update
DELETE /api/vedtak/{id}               # Delete

# ✅ Sub-resources
GET    /api/vedtak/{id}/aktiviteter   # List child resources
POST   /api/vedtak/{id}/aktiviteter   # Create child resource

# ✅ Actions (verb as sub-resource)
POST   /api/vedtak/{id}/godkjenn      # State transition

# ❌ Wrong
GET    /api/getVedtak                 # Verb in URL
GET    /api/vedtak/hentAlle           # Verb in URL
POST   /api/createVedtak              # Verb in URL
GET    /api/Vedtak                    # PascalCase

Error Handling (RFC 7807 / ProblemDetail)

// Spring Boot 3+ — built-in ProblemDetail support

@RestControllerAdvice
class ErrorHandler {
    @ExceptionHandler(ResourceNotFoundException::class)
    fun handleNotFound(ex: ResourceNotFoundException): ProblemDetail =
        ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.message ?: "Resource not found").apply {
            title = "Resource not found"
            setProperty("resourceType", ex.resourceType)
            setProperty("resourceId", ex.resourceId)
        }

    @ExceptionHandler(MethodArgumentNotValidException::class)
    fun handleValidation(ex: MethodArgumentNotValidException): ProblemDetail =
        ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Validation failed").apply {
            title = "Invalid request"
            setProperty("errors", ex.bindingResult.fieldErrors.map {
                mapOf("field" to it.field, "message" to it.defaultMessage)
            })
        }
}

For Ktor, use the StatusPages plugin:

install(StatusPages) {
    exception<ResourceNotFoundException> { call, cause ->
        call.respond(HttpStatusCode.NotFound, ProblemResponse(
            title = "Resource not found",
            status = 404,
            detail = cause.message ?: "Resource not found",
            instance = call.request.uri,
        ))
    }
    exception<ValidationException> { call, cause ->
        call.respond(HttpStatusCode.BadRequest, ProblemResponse(
            title = "Invalid request",
            status = 400,
            detail = "Validation failed",
            errors = cause.errors,
        ))
    }
}